First-time Setup

Complete three tasks before creating an instance: connect a node, prepare an environment, and configure a model provider.

1. Check the Local Node

A full server installation or the desktop app normally connects its local node automatically. Open Settings → Nodes and confirm that it is online. Use Add local node to retry synchronization if it is missing.

Connect a Remote Node

1. Open Settings → Nodes.
2. Select Add node and follow the connectivity wizard.
3. Copy the complete install command generated by the interface.
4. Run it with administrator privileges on the remote Debian/Ubuntu host.
5. Return to the control plane and wait for Node connected.

The command contains a one-time join token and a release version matched to the current control plane. Do not post the token publicly or commit it to a repository.

2. Prepare a Runtime Environment

Open Settings → Images. Market images are read-only catalog entries; custom images are references added by an administrator.

Docker must be installed and running on the target node before creating a Docker instance. The creation wizard verifies the daemon and indicates whether an image is ready or must be pulled.

You can also save an existing Docker instance as an environment template. A template captures software and tools in the writable container layer, but excludes /workspace, /data, /home/agent, other mounts, memory, and running processes.

3. Configure a Model Provider

1. Open Settings → Models.
2. Add a model provider.
3. Select the application, primarily Codex or OpenCode.
4. Enter the endpoint, API key, and model names.
5. Test the connection and save it.

Codex primarily uses openai-responses; OpenCode primarily uses openai-chat-completions. Never place API keys in documentation, prompts, or project files. After creating an instance, use Instance settings → Models to select available providers and their order.

See Codex and OpenCode for the complete comparison.

Optional: Add a Project

Register Git repositories under Settings → Projects, or add one directly from the instance creation wizard. For private repositories, configure an HTTPS token or SSH credential under Settings → Git credentials first.