Configuring Runtimes

This guide explains how to configure and manage Agent Runtimes in Sink. A Runtime defines how to launch and run an AI Agent (such as Claude Code, Codex, etc.).

Prerequisites

• Sink binary installed
• Basic familiarity with Agent Client Protocol (ACP)
• Internet access to download Runtimes from the ACP registry

What is a Runtime

A Runtime is a configuration that defines the process for launching a specific Agent:

• ID: A unique identifier (e.g., claude-code, codex)
• Name and Description: Human-readable Runtime information
• Distribution Method: Specifies how to launch the Agent (via npm package or local command)
• Environment Variables: Configuration needed when starting the Agent

All Runtime configurations are stored in ~/.sink/runtimes.json.

Adding Runtimes

The simplest way is to add Runtimes using the interactive command:

Run the Create Command

sink runtime create

This command will:

1. Prompt you to choose between “From ACP registry” (browse and install from the official registry) or “Manual entry” (enter runtime details manually)
2. If using the registry: fetch available agents from the ACP registry (only agents with npm package distribution are shown), display an interactive selection menu, then write the selected Runtimes to runtimes.json
3. If manual entry: prompt for runtime ID, distribution type (npx or local), package/command, and arguments

Note: The ACP registry flow in runtime create fetches agents with npm/npx distribution only. This is different from init, which detects locally installed Builtin Runtimes (Claude Code, Codex, Factory Droid, OpenCode) by probing local commands. Both approaches populate runtimes.json but through different mechanisms.

Registry Example

$ sink runtime create
  ✔ Sink — Create Runtime
  ◆ How would you like to add a runtime?
  │  ● From ACP registry  /  ○ Manual entry
  ...
  ✔ Fetched 5 compatible agents from ACP registry (5 total)

  ✔ Select agent runtimes to install
  ⊙ agent-x         Agent X (some-agent-x)
  ◯ agent-y         Agent Y (some-agent-y)

  ✔ Synced 1 runtime (added: 1, replaced: 0)

Note: The actual agent names shown depend on the ACP registry content. The example above is illustrative.

After adding, the new Runtimes are immediately available without requiring a Gateway restart.

Viewing Installed Runtimes

View all configured Runtimes:

sink runtime list

Example output:

  ✔ Sink Runtimes
  ℹ claude-code — Claude Code v1.0.0
    $ npx -y @anthropic/claude-code
  ℹ codex — Codex v2.1.0
    $ npx -y @anthropic/codex --mode interactive
  ✔ 2 runtimes installed

Disabling a Runtime

To disable a Runtime without deleting it, set the disabled field to true under metadata:

{
  "agentRuntimes": {
    "old-agent": {
      "description": "Old Agent",
      "metadata": {
        "disabled": true
      },
      "distribution": {
        "npx": {
          "package": "@myorg/old-agent"
        }
      }
    }
  }
}

Disabled Runtimes won’t appear in the UI, but the configuration is preserved.

Troubleshooting

Issue: Running sink runtime create with the registry option fails with connection error

Solution:

• Check your network connection
• Verify access to the ACP registry: curl https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json
• Try adding the Runtime manually

Issue: Runtime fails to start with “command not found” error

Solution:

• Verify that distribution.npx.package or distribution.local.cmd is correct
• Ensure the npm package is published or the local command file exists and is executable
• Check that environment variables are set correctly

Issue: Runtime startup is missing environment variables

Solution:

• Confirm the environment variables are set in your system: echo $VAR_NAME
• Check the interpolation syntax in the Runtime configuration’s env field
• If running in a systemd service, verify that EnvironmentFile or Environment includes the required variables

Next Steps

After configuring Runtimes, you can:

1. Create Profiles to associate Runtimes with Agent personality configurations
2. Get Started and create your first Task