Stable identifier
Ordinary remote development setup does not require writing a manifest. Open Organization Settings → Agent workspaces and complete these tasks in order:
- Check whether OpenCode or Pi is ready.
- Connect DeepSeek, OpenAI, Anthropic, or a compatible provider under Model connections.
- Choose an approved Workspace Profile when creating the Workspace.
A model API key belongs to the provider connection, not to OpenCode or Pi, and must never be placed in an Adapter or Profile manifest. The manifest workflow below is for custom integration authors and appears under Custom integrations in the Web console.
An Agent Adapter is a declarative, immutable agent integration definition — it describes the required Sandbox template, runtime, capabilities, interaction modes, persistence paths, and credential types. Appaloft never loads code from a manifest, and never accepts arbitrary shell command strings.
Every install belongs to the current organization: two organizations can install a definition with the same digest, but can’t see or operate each other’s installations. Organization members can view installations; organization admins can validate, install, disable, and uninstall.
Input fields and validation
A minimal Codex terminal/headless adapter manifest example (replace the template id, version, digest, and runtime version range with values already admitted on your current Appaloft instance):
{
"schemaVersion": "appaloft.agent-adapter/v1",
"id": "codex",
"displayName": "Codex",
"version": "1.0.0",
"kind": "declarative",
"requirements": {
"adapterApi": "^1.0.0",
"sandboxTemplate": {
"id": "agent-workspace",
"version": "^1.0.0",
"digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
},
"runtimes": [{ "id": "codex", "version": "^1.0.0" }],
"capabilities": { "required": ["managed-terminal", "headless"], "optional": [] }
},
"interactionModes": [
{
"id": "terminal",
"transport": "terminal",
"command": ["codex"],
"eventFidelity": "raw-pty",
"sessionRecovery": "process-lifetime"
},
{
"id": "headless",
"transport": "headless",
"command": ["codex", "exec"],
"taskInput": "append-argument",
"eventFidelity": "line-events",
"sessionRecovery": "managed-run-lineage"
}
],
"persistentPaths": ["/workspace/.codex"],
"healthcheck": { "kind": "process" },
"credentials": []
}Only adapters with a long-running Runtime declare top-level start; for example, OpenCode uses
["opencode", "serve", "--hostname", "0.0.0.0", "--port", "4096"]. It is a bounded argv
array, never a shell string, and runs only inside the Sandbox. For native attach, start, the attach
serverPort, and the HTTP healthcheck must target the same port. Appaloft marks the Runtime ready
only after the child remains running and the healthcheck succeeds; failure terminates the exact
child and revokes its credential grant. Terminal/headless-only adapters do not need start and may
keep a process healthcheck.
Command / interface examples
# Validation only returns the normalized digest and compatibility result — it never persists data or starts an agent
appaloft agent-adapter validate ./codex.agent-adapter.json
appaloft agent-adapter install ./codex.agent-adapter.json
appaloft agent-adapter list
appaloft agent-adapter show <installation-id>You can also paste a manifest under Organization Settings → Agent workspaces → Custom integrations to validate then install.
Workspace configuration templates
A Workspace configuration template combines a specific adapter definition, Sandbox template, run limits, initialization commands, default ports, and check commands into a reusable creation entrypoint. It doesn’t execute any install script, and doesn’t create a new Workspace aggregate — before creating a Workspace, Appaloft compiles the template and pins the resolved adapter digest, Sandbox template digest, harness, and capability snapshot onto the runtime.
{
"schemaVersion": "appaloft.agent-workspace-profile/v1",
"id": "codex-standard",
"displayName": "Codex Standard",
"version": "1.0.0",
"adapter": {
"id": "codex",
"version": "1.0.0",
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"interactiveModeId": "terminal",
"taskModeId": "headless"
},
"harnessTemplateId": "aht_codex_declarative_v1",
"sandbox": {
"template": {
"id": "agent-workspace",
"version": "1.0.0",
"digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
},
"requestedIsolation": "container-trusted",
"limits": { "cpuMillis": 2000, "memoryBytes": 4294967296, "diskBytes": 21474836480, "maxProcesses": 128 },
"networkPolicy": { "mode": "deny" }
},
"workingDirectory": "/workspace",
"initialization": [{ "id": "verify-codex", "argv": ["codex", "--version"] }],
"defaultPorts": [],
"persistentPaths": ["/workspace/.codex"],
"suggestedChecks": []
}appaloft agent-workspace-profile validate ./codex.profile.json
appaloft agent-workspace-profile install ./codex.profile.json
appaloft agent-workspace-profile list
appaloft agent-workspace-profile compile <installation-id>Organization admins can do the same in Organization Settings → Workspace Configuration Templates. Developers pick an enabled template on the Workspaces page to create a Workspace; an unavailable capability keeps the corresponding button disabled, rather than silently degrading after creation.
Error codes and recovery hints
Disabling blocks new Workspaces from resolving that installation, but doesn’t break the recovery references of existing Workspaces:
appaloft agent-adapter disable <installation-id>Uninstalling is only allowed when no active Workspace still references the installation; if a reference exists, the server returns a conflict and keeps the installation record:
appaloft agent-adapter uninstall <installation-id>Uninstalling only deletes the installation record for the current organization — it doesn’t delete the immutable definition itself, which may be shared by other organizations, and doesn’t terminate any existing Sandbox or agent process. Workspace configuration templates use exactly the same disable and reference-protection semantics:
appaloft agent-workspace-profile disable <installation-id>
appaloft agent-workspace-profile uninstall <installation-id>