Quick Start

Run your first AFK coding-agent session from the browser in about five minutes. This page is the first-session path: connect a daemon, pick a model, spawn work, and see it in the dashboard.

What you will have at the end

• A connected daemon that can see a local project checkout
• At least one model connection in Account → LLM
• A live browser session with a prompt, tool trail, and approval controls

Step 1 — Connect a daemon

AFK's browser app is the command surface. The daemon is the runner next to your code. Create a daemon token in Account → API Keys, then install and start the daemon on the machine that has the repository:

curl -fsSL https://afk.mooglest.com/install.sh | bash -s -- afk_your_key_here

On Windows PowerShell, the published binary currently needs -AllowUnsigned. Full macOS, Linux, Windows, and service instructions are on Installation.

Return to the browser and confirm your machine appears in the connected daemons list. If it does not, check the token, network access, and the daemon's configured home/project directory.

Step 2 — Add a model connection

Open Account → LLM and add a connection. AFK is bring-your-own-key: paste an API key, complete a supported subscription flow, or bind a local OpenAI-compatible endpoint such as Ollama or LM Studio. Click Test before spawning.

If a provider's model list looks incomplete, keep the manual model field. Provider discovery is not always exhaustive. See LLM Providers for connection details.

Optional — Bring your setup

Already using Claude Code or Codex in this repository? Open Help → Import project setup to review project-scoped setup before starting an AFK session. This is a selective import, not a full migration of your account or agent environment.

1. Select a connected Daemon and enter the Project directory on that machine. Discovery checks Claude Code and Codex setup together; there is no source selector.
2. Click Scan project. Scanning previews candidates and their destinations; it does not change files.
3. Under Review candidates, review each result and its explanation. Manually select only the supported items you want.
4. Before requesting contents, confirm the consent checkbox: selected file contents will travel through the AFK server to this browser for review. Free-form content may contain secrets, even when known credential files are blocked. Click Review selected contents only if you accept that transfer.
5. Review the selected contents and proposed destinations, then click Import selected to apply the reviewed selection.
6. Read Import results and review the resulting project changes before using them. Import does not run commands, start MCP servers, test connections, or reload existing sessions.

What can be reused

• Compatible instructions and skills: existing AGENTS.md and skills in .agents/skills/ are recognized in place; they do not need duplicate AFK copies.
• Claude instructions: copy either CLAUDE.md or .claude/CLAUDE.md to AGENTS.md only when it is absent. Choose one source if both exist. Existing instructions are never automatically merged or overwritten.
• Claude skill bundles: skills from .claude/skills/ can be copied to .afk/skills/ with their supporting files, subject to safety and size limits. Bundles rejected during scanning are not offered as partial skills. Each skill needs valid YAML frontmatter with a name matching its directory and a nonblank description. Only name, description, license, compatibility, and metadata fields are supported; tool restrictions, invocation controls, agent/context settings, hooks, and unknown fields require manual migration rather than being silently discarded. Dynamic command injection and argument placeholders also block skill import. Legacy .claude/commands entries are reported for manual migration, not copied as skills. Review scripts and instructions before later invoking a skill.
• Project MCP configuration: choose one supported .mcp.json or .codex/config.toml source to create .afk/mcp.json only when it is absent. The source must contain only its MCP server section, except that Codex model, model-provider, and reasoning-effort settings are explicitly ignored rather than imported. Import accepts a restricted command configuration without arguments, or an HTTP URL without credentials, query parameters, or fragments. Environment values, headers, authentication, nonempty arguments, unrelated settings, and unsupported transports block import. AFK's broader MCP runtime support does not imply importer compatibility.

Conflicts, unsupported items, and next steps

Available means the item is already recognized without copying. Ready means it is eligible for selection. Conflict means an existing destination must be reviewed manually; import will not replace it. Blockedentries are not selectable: read the explanation, then use AFK's own configuration screens or edit your project deliberately. If files change after scanning, scan again rather than assuming the earlier preview still applies. Changing the selected scope invalidates the preview; after an apply error, use Scan again to obtain a fresh preview.

Use a project inside the daemon's configured home directory, not the home directory itself. Symlinks, special files, known credential filenames, and oversized or deeply nested bundles are blocked. These checks cannot guarantee that arbitrary instruction or script text contains no secrets: inspect and trust the source before importing. Use a trusted workspace and pause other tools or people modifying it during scan, review, and import. These checks do not provide race-safe containment against adversarial concurrent filesystem changes. An I/O failure during apply may leave partial files; review the reported results and project changes before retrying.

Step 3 — Spawn the first session

Click New session in the sidebar. Choose the connected daemon, a project directory it can access, and a model. Describe a bounded first task, for example:

summarise this repository and list the failing tests

Browser-created local sessions default to the original project path. Pick Worktree only when you want an isolated git worktree. For a remote Docker session, paste a repository URL or connect the GitHub App in Account → Git.

You can also spawn from the CLI after the daemon is running:

afk spawn \
  --project /home/you/projects/myapp \
  --task "summarise this repository and list the failing tests"

Step 4 — Watch the session, then steer it

The session should appear immediately in the dashboard. Open it and confirm you can see the prompt, streaming reply, and any tool calls. This is the difference from a terminal-only agent: the run stays visible if you leave the tab.

• In auto mode, reads run freely and writes or shell commands wait for approval.
• Use plan mode when you want the agent to inspect first and wait before editing.
• If the agent asks a question or requests approval, answer from the same session instead of starting a second one.

Permission modes and approval behaviour are documented in Permission Modes. Dashboard, composer, and session controls are in the Browser UI Guide.

If something does not appear

• Daemon missing: recreate the API key, confirm the daemon process is running, and check that it can reach AFK outbound.
• Project path missing: the directory must be inside the daemon's configured home/project access path.
• Model test fails: verify the connection, base URL, and whether a local endpoint is bound to the daemon that can reach it.
• Session starts but looks stuck: look for a pending approval, plan review, or question in the transcript before assuming the agent stopped.

Next steps