Configuration

Jetsyn ships with working defaults, so most of these you never touch. When you do need to reach in, configuration comes in two forms: environment variables that tune the runtime and choose how the CLI reaches your cell, and a small set of files inside the cell that carry the contracts your employees read and write.

Two forms of configuration#

Everything a builder touches falls into three groups. Two are environment variables, one on each side of the wire; the third is a handful of files on the cell's /workspace volume that every surface agrees on.

• Runtime and agent tuning shape how an employee process launches inside the cell: which model and effort it runs at, when it is considered stalled, and what a Pro terminal opens into.
• CLI transport lives in your shell and decides how jetsyn reaches the cloud cell: the connect mode, the box, the key, the default cell, the token, and the endpoints.
• Cell files are the config-file contracts on the cell volume: the shared company record, the Brain the strategist writes, the live roster, the intent output seam, and the agent-to-UI render file.

Runtime and agent tuning#

These control how an employee launches inside the cell. The headless runtime, the one that answers gateway events, and the interactive jetsyn agent REPL each carry their own launch knobs, so you can tune one without disturbing the other.

# Set in the cell environment; the defaults are already sane
export JETSYN_MODEL=claude-opus-4-8
export JETSYN_EFFORT=xhigh
export JETSYN_STALL_TIMEOUT_SECONDS=600

CLI transport#

These live in the shell where you run jetsyn. Mediation, whether you get a direct or a conversational session, is decided by the in-cell command, never by the transport, so these variables only affect how the CLI reaches your cell. When JETSYN_CONNECT is unset the CLI picks SSH if an SSH key is present, otherwise HTTPS.

export JETSYN_CONNECT=https
export JETSYN_CELL=acme
jetsyn agent          # connects to the acme cell over HTTPS

Files in the cell#

All customer data is folders on the cell's /workspace volume. A few files there are not data but contracts: every surface agrees on their shape, so an employee that writes one and a surface that reads it stay in sync with no shared code.

workspace.json

The shared record is a small, whitelisted object. Only name, idea, slug, status, and plan are accepted; anything else is dropped. Write it cell-canonical and it shows up identically on the web workspace and the CLI.

{
  "name": "Acme Robotics",
  "idea": "AI employee for our support inbox",
  "slug": "acme",
  "status": "active",
  "plan": "business"
}

The agent-to-UI contract

Each employee renders itself by writing a ui.json under .claude/agents/<id>/. It is version 1 of a closed contract: a fixed set of block primitives, text, markdown, list, kv, link, preview, and action. Writes are atomic, so a surface never reads a half-written file, and unknown keys are rejected, which is what lets every surface render every employee without per-employee UI code.

Where to go next#