Documentation

Usage

Agents and projects

#Agents

Default runners: bash, claude, codex, agy, and opencode. Legacy configuration may add more. Install and authenticate only the runners you choose, following each provider's instructions. Check using the same user and environment as the server:

command -v bash
command -v claude
command -v codex
command -v agy
command -v opencode

Check only the tools you installed:

claude --version
codex --version
agy --version
opencode --version

Open each CLI directly and complete an interaction before using it in Cockpit. Restart the server and refresh agent discovery after installing or authenticating.

Models, effort, and accounts depend on the runner. Codex may read models from its local cache; others use their own configuration or discovery. An old profile listing a model does not guarantee access. Delegation preserves the recipient's configured runner and model.

#Connect accounts in Settings

Under Settings → Connections, choose Codex, Claude, or Antigravity, then Add account → Sign in with browser. The CLI must be installed on the server but does not need an authenticated session. A nickname is optional and does not replace login. Use All to find unconfigured runners.

Connections support search and filters; accounts and models appear in provider details. Enable provider controls availability for new team members without affecting open sessions. DeepSeek accepts an API key. Connect gateway registers a name, base URL, OpenAI format (Chat Completions or Responses), and optional key. Testing queries /models, without paid inference. Keys are encrypted on the server. Responses can use Codex or DSH; Chat Completions uses DSH. Remote URLs require HTTPS. Localhost refers to the Cockpit server.

In Settings → Execution, enable or disable DSH for new sessions. Enabling prepares its isolated directory automatically if the harness is installed. Otherwise, the interface explains setup and lets you use an installed CLI. Disabling DSH or a provider does not close sessions; new sessions and restarts use the new settings. Languages are under Preferences. Choices are saved in <COCKPIT_HOME>/integrations.json (default ~/.cockpit).

  • Codex: open the login link and enter the device code shown. This also works on a VPS.
  • Claude: authorize in your browser. If asked for a code, use the authorization option in Settings.
  • Antigravity: authorize your Google account. If local callback fails on a VPS, copy the full browser URL into the manual redirect option. The server needs AGY_OAUTH_CLIENT_ID and AGY_OAUTH_CLIENT_SECRET, or ~/.cockpit/agy-oauth.json containing clientId and clientSecret. The callback uses a temporary local port, state, and PKCE, following Google's OAuth documentation.

Each account has its own directory in ~/.cockpit/profiles/. After login, it joins the pool and becomes selectable for team members. Accounts are recorded in ~/.cockpit/accounts.json; COCKPIT_HOME changes the root. Existing catalog accounts remain available. Pending login can be canceled and expires after ten minutes.

#Projects

Open, prepare, or clone a project through the interface. Choose a writable folder. The picker browses folders on the server, even from another device. The historical starting path is /DATA/Projetos; use your actual path elsewhere.

To prepare a new project manually:

mkdir -p "$HOME/Projetos/my-app"
cd "$HOME/Projetos/my-app"
git init
git config user.name "Your Name"
git config user.email "you@example.com"
git commit --allow-empty -m "Initialize project"

The initial commit makes HEAD resolvable for isolation and review. In existing repositories, check git status and preserve ongoing changes. Private clones require configured Git/SSH credentials; the backend disables interactive Git prompts.

From the Cockpit checkout, start on another project:

node bin/cockpit.js --cwd "$HOME/Projetos/my-app" --host 127.0.0.1

--cwd sets the instance's initial project and persistence root. You do not need a Cockpit copy in every project.