# Use GizDesk

GizDesk is the open-source AI agent platform built on Gizlang, GizWeb and GizDB. It gives agents conversations,
tools, skills, memory, scheduled work and a workspace for their results. GizStack is the separately operated cloud
service; you do not need a cloud account to run Desk locally.

## Start and keep an editable copy

[Install the toolchain](../quickstart.md), then create the application:

```sh
giz init my-desk --template desk
cd my-desk
giz run main.giz
```

Open `http://127.0.0.1:8080`. The project holds the app source; `data/` holds its local data. Use
`giz live main.giz` while editing the source. `giz desk` launches the bundled application instead.

## Choose a model

Use a local model, or open **Connections** to sign in to ChatGPT, paste API keys, add an OpenAI-compatible server, or
import the accounts Codex, opencode and CLIProxyAPI already hold. Add several accounts of a provider and each turn uses
the first ready one, moving on when one reaches its limit.
The [model selection contract](agent.md#choose-a-model-and-connect-tools) explains local and account model names.
Local models download weights and may need substantial memory and disk space; see
[Compute and generative AI](compute.md#before-you-start) before starting one.

## Complete a first task

The account and computer boundary is available from **Connections**. See the current screen in the
[GizDesk guidebook](../labs/gizdesk.md#model-accounts-and-computer-connections).

1. Start a conversation and choose a model. Ask for an answer that requires no external tools first.
2. Review its answer and model selection. Stop a running answer with the Stop control.
3. Open the agent settings to configure instructions, permissions and tools. Connect an MCP server only when you
   intend to give the agent its capabilities; configure its address and credentials there.
4. Ask for a document or code result and open it beside the conversation. Code is displayed as text in this viewer.
5. Close and reopen the page to find the stored conversation and result.

Skills describe how to do a task; memory stores reusable context; knowledge sources provide reference material.
They are separate from permission to execute tools. Review approvals before a tool changes data.

## Configure the application

| Setting | Purpose |
| --- | --- |
| `GIZDESK_PORT` | Listener port; default 8080 |
| `GIZDESK_DATA` | Data folder; default `data` in the launch directory |
| `GIZDESK_SECURE` | Opt into the app's owner authentication mode |
| `GIZDESK_MAIL_URL` | Default mailer (`smtp://`, `smtps://`, `ses://`, `resend://`) for Drive invitations and sign-in links |
| `GIZDESK_OFFICE_URL` | Default office engine (Collabora Online or ONLYOFFICE Docs, by WOPI) |
| `GIZDESK_OFFICE_REACH` | The Desk's address as the office engine reaches it, when it differs from the browser's |

Connections → *Services* sets the same three for a running Desk, and the speech and talking-head workers of character
chat (kept in `GIZDESK_DATA/services.json`). The Desk's Drive answers S3 at its own address for its access keys (bucket
`desk`, path style), and streams uploads and downloads of any size.

The app's [deployment and security instructions](https://github.com/gizai/gizlang/tree/main/desk#secure-single-owner-mode)
own the full owner setup and media-worker setup. Keep the default application local until that setup is complete.

## Source, Computer and deployment

When a Desk or any GizStack starter is hosted, the source has one owner: the app project's Giz Drive working tree. The
browser, CLI and Agent builder use that same source. A Giz Computer is the execution boundary: it checks the source,
runs its tests and prepares the candidate. GizStack's App resource then publishes the verified immutable deployment.

The Agent builder follows the same path as a developer: read the current source, make a complete checked change, run the
focused tests and open a preview. Production data stays unchanged until a person promotes the preview. Rollback
publishes an earlier deployment source again; it does not create a second source store. This applies equally to Desk,
Todo and other starter or user-created apps.

Use the [GizStack deployment guide](https://gizstack.com/docs/platform/deploy) for the console flow and
[`giz-account`](giz-account.md) for Drive, Computer and App commands. The local command `giz deploy` uses the same
deployment owner for terminal work.

## Current boundaries and next steps

External tools and speech/media models require configuration. Available capabilities depend on those connections;
an agent profile alone does not provide an isolated terminal or browser. The
[app's capability table](https://github.com/gizai/gizlang/tree/main/desk#openclaw-and-hermes-capability-mapping)
lists current boundaries. [Build typed tools](agent.md) to extend an agent and
[use GizWeb](web.md) to change the application. Classical [ML](ml.md) is one possible capability, not the definition
of the agent platform.

Use GizDesk

GizDesk is the open-source AI agent platform built on Gizlang, GizWeb and GizDB. It gives agents conversations, tools, skills, memory, scheduled work and a workspace for their results. GizStack is the separately operated cloud service; you do not need a cloud account to run Desk locally.

Start and keep an editable copy

Install the toolchain, then create the application:

giz init my-desk --template desk
cd my-desk
giz run main.giz

Open http://127.0.0.1:8080. The project holds the app source; data/ holds its local data. Use giz live main.giz while editing the source. giz desk launches the bundled application instead.

Choose a model

Use a local model, or open Connections to sign in to ChatGPT, paste API keys, add an OpenAI-compatible server, or import the accounts Codex, opencode and CLIProxyAPI already hold. Add several accounts of a provider and each turn uses the first ready one, moving on when one reaches its limit. The model selection contract explains local and account model names. Local models download weights and may need substantial memory and disk space; see Compute and generative AI before starting one.

Complete a first task

The account and computer boundary is available from Connections. See the current screen in the GizDesk guidebook.

Start a conversation and choose a model. Ask for an answer that requires no external tools first.
Review its answer and model selection. Stop a running answer with the Stop control.
Open the agent settings to configure instructions, permissions and tools. Connect an MCP server only when you intend to give the agent its capabilities; configure its address and credentials there.
Ask for a document or code result and open it beside the conversation. Code is displayed as text in this viewer.
Close and reopen the page to find the stored conversation and result.

Skills describe how to do a task; memory stores reusable context; knowledge sources provide reference material. They are separate from permission to execute tools. Review approvals before a tool changes data.

Configure the application

Setting	Purpose
`GIZDESK_PORT`	Listener port; default 8080
`GIZDESK_DATA`	Data folder; default `data` in the launch directory
`GIZDESK_SECURE`	Opt into the app's owner authentication mode
`GIZDESK_MAIL_URL`	Default mailer (`smtp://`, `smtps://`, `ses://`, `resend://`) for Drive invitations and sign-in links
`GIZDESK_OFFICE_URL`	Default office engine (Collabora Online or ONLYOFFICE Docs, by WOPI)
`GIZDESK_OFFICE_REACH`	The Desk's address as the office engine reaches it, when it differs from the browser's

Connections → Services sets the same three for a running Desk, and the speech and talking-head workers of character chat (kept in GIZDESK_DATA/services.json). The Desk's Drive answers S3 at its own address for its access keys (bucket desk, path style), and streams uploads and downloads of any size.

The app's deployment and security instructions own the full owner setup and media-worker setup. Keep the default application local until that setup is complete.

Source, Computer and deployment

When a Desk or any GizStack starter is hosted, the source has one owner: the app project's Giz Drive working tree. The browser, CLI and Agent builder use that same source. A Giz Computer is the execution boundary: it checks the source, runs its tests and prepares the candidate. GizStack's App resource then publishes the verified immutable deployment.

The Agent builder follows the same path as a developer: read the current source, make a complete checked change, run the focused tests and open a preview. Production data stays unchanged until a person promotes the preview. Rollback publishes an earlier deployment source again; it does not create a second source store. This applies equally to Desk, Todo and other starter or user-created apps.

Use the GizStack deployment guide for the console flow and giz-account for Drive, Computer and App commands. The local command giz deploy uses the same deployment owner for terminal work.

Current boundaries and next steps

External tools and speech/media models require configuration. Available capabilities depend on those connections; an agent profile alone does not provide an isolated terminal or browser. The app's capability table lists current boundaries. Build typed tools to extend an agent and use GizWeb to change the application. Classical ML is one possible capability, not the definition of the agent platform.