Quick Start

This tutorial walks you through the complete first-time Sink workflow: initialize configuration, start the Web UI, and create and run your first AI task.

Prerequisites

• The sink binary is in your PATH (provided by the distribution)
• At least one supported Agent Runtime is installed locally (see Runtime requirements below)

Runtime Requirements

Each Builtin Runtime has specific prerequisites:

Step 1: Initialize Configuration

Run the initialization command:

sink init

init runs the following interactive flow:

1. Detect Installed Runtimes

◆ Sink Init
⠋ Detecting installed agent runtimes...
✔ Detected 2 available runtime(s)

The system scans for locally installed Builtin Runtimes (Claude Code, Codex, Factory Droid, OpenCode). If no supported Runtime is found, the command prints install instructions and exits.

2. Select Default Profile Runtime

The system displays available Runtimes with version hints. Use the arrow keys to select, then press Enter:

◆ Select runtime for the default profile
│  ● claude-code   Claude Code (3.2.0 + claude-agent-acp)
│  ○ codex         OpenAI Codex (0.130.0 + codex-acp)
│  ○ factory-droid Factory Droid (0.120.0)
│  ○ opencode     OpenCode (1.14.0)
└

Unavailable Runtimes are shown as disabled with a reason (e.g., “not found” or “outdated”).

3. Probe Runtime and Configure Default Profile

The system probes the selected Runtime via ACP to discover configuration options (model, mode, etc.), then prompts you to configure the default Profile:

◆ Profile name
│  Default Profile (Claude Code)
◆ Default model
│  ● sonnet[1m]
│  ○ opus
│  ○ haiku
◆ Profile description
│  Generic agent using Claude Code
◆ System prompt / instructions (optional)
│

You can optionally create additional Profiles with different Runtimes.

4. Review and Confirm

The system shows a diff preview of all files to be written:

── Write Plan ─────────────────────────────────────────
runtimes.json (create)
  + {"agentRuntimes":{"claude-code":{...}}}
settings.json (create)
  + {"env":{},"logLevel":"info"}
gateway.json (create)
  + {"port":5000,"logLevel":"info","authTokens":[]}
mcp.json (create)
  + {"mcpServers":{}}
profiles/default.md (create)
  + ---
  + name: default
  ...
skills/ (create directory)
────────────────────────────────────────────────────────
◆ Proceed with write? (Y/n)

5. Optional: Install from Marketplace

If a default marketplace is configured, the system offers to install recommended resources:

◆ Install recommended resources from default marketplace [cclab/marketplace]? (Y/n)

When complete:

✔ Sink is ready

Step 2: Verify the Default Profile

After init completes, check the default Profile:

cat ~/.sink/profiles/default.md

The content will look similar to (the exact configDefaults depend on the Runtime’s ACP probe results):

---
name: default
description: Generic agent using Claude Code
runtime: claude-code
configDefaults:
  model:
    type: string
    value: sonnet[1m]
    candidates:
      - opus
      - sonnet[1m]
      - haiku
---

If adjustments are needed, edit this file directly. The runtime value must match a Runtime ID in runtimes.json.

Step 3: Start the Gateway

sink gateway start

After successful startup, you will see JSON log output similar to:

{"level":30,...,"mode":"release","version":"...","msg":"Gateway starting"}
{"level":30,...,"workspaceId":"default","msg":"WorkspaceProxy connected to WorkspaceHost"}
{"level":30,...,"workspaceId":"default","transport":"local","msg":"WorkspaceProxy connected"}
{"level":30,...,"msg":"GatewayWorkspaceManager started: 1 workspaces"}
{"level":30,...,"msg":"Boot checks passed"}
{"level":30,...,"msg":"Gateway listening on port 5000"}

Boot checks passed indicates configuration validation succeeded. If this line is missing and a fatal error appears, the configuration has issues (see FAQ).

The default listening address is 127.0.0.1:5000. To specify a different port or address:

sink gateway start --port 8080 --host 0.0.0.0

Step 4: Access the Web UI

Open your browser and visit:

http://127.0.0.1:5000

You will see the Sink Web UI main interface, with the navigation bar on the left and the workspace in the center.

Step 5: Create and Run Your First Task

1. Click “New Task” in the top toolbar
2. Enter a task description (e.g., Analyze security issues in this Python code)
3. Select “Default” from the Profile dropdown menu
4. Click “Create” to create the task

After creation, the interface navigates to the task view, with the status progressing from created -> routing -> generating -> running.

In the input box at the bottom, send your first message to the Agent:

Hello, please introduce yourself and explain what you can help me with.

Press Enter to send. The Agent begins streaming its response, and you can watch its reasoning process in real time.

If the Agent needs to perform an action (such as running a command or writing a file), a permission approval prompt will appear. Click “Approve” or “Deny”.

FAQ

fatal: No runtimes configured

runtimes.json is empty or does not exist. Run sink init to detect and configure Runtimes. Ensure at least one Runtime (Claude Code, Codex, Factory Droid, or OpenCode) is installed locally.

fatal: No default profile found

profiles/default.md does not exist. Run sink init to create it, or manually create the file (see Step 2 above).

fatal: Default profile references unknown runtime '...'

The runtime field in profiles/default.md does not match any ID in runtimes.json. Check that the IDs match on both sides:

cat ~/.sink/runtimes.json | head -10
cat ~/.sink/profiles/default.md | head -8

Agent not responding

Check whether the selected Runtime is properly installed and executable. Run sink init — it will probe the Runtime and report any issues (version too old, missing companion tools, etc.).

Next Steps

• Managing Profiles – Create dedicated Agent persona configurations
• Configuring Runtimes – Add more ACP Agents
• Configuring MCP Servers – Provide additional tools for Agents