How Agents Work

Every Whim task runs an AI coding agent inside an isolated cloud container. This page explains what’s in that container, how it gets configured, and how the agent interacts with your workspace.

​

The container environment

When you launch a task, Whim provisions a dedicated Ubuntu container on Fly.io. The container includes:

• Your repo — cloned and checked out on a fresh branch
• The AI coding agent — Claude Code, Codex CLI, or a CCR (Claude Code Router) session, depending on your provider
• A full dev environment — shell, git, Node.js, and common dev tools
• Whim services — background processes that handle proxying, state tracking, and workspace integration

The agent has the same capabilities it would have on your local machine — it can read and write files, run shell commands, install packages, start dev servers, and create pull requests. The difference is that it’s running in an isolated sandbox, on its own branch, with your configuration pre-loaded.

​

What gets injected

Before the agent starts, Whim injects your workspace and user configuration into the container. This configuration comes from three layers, merged in priority order:

1. Workspace defaults — set by workspace admins for all tasks
2. User defaults — your personal preferences across workspaces
3. Per-workspace user config — your overrides for this specific workspace

Higher-priority layers override lower ones. Here’s what gets injected:

​

Instructions

Your custom instructions (the equivalent of a CLAUDE.md file) are written to /app/CLAUDE.md in the container. These are loaded automatically by the agent at startup and guide its behavior throughout the task — coding standards, architectural context, project-specific rules. Instructions from all three config layers are concatenated together, so workspace-level and user-level guidance both apply.

​

Skills

Skills are reusable prompt templates that agents can invoke with /<skill-name> during a task. They’re injected as files into the agent’s skill directory:

• Claude: /home/node/.claude/skills/
• Codex: /home/node/.codex/skills/

Skills can be single-file or multi-file, and are normalized to Markdown for consistency across providers.

​

MCP servers

MCP (Model Context Protocol) servers extend the agent’s capabilities with external tools and data sources. Your configured MCP servers are written to the provider’s config file:

• Claude: /home/node/.mcp.json
• Codex: /home/node/.codex/config.toml

In addition to any MCP servers you configure, Whim always injects its own built-in MCP server — more on that below.

​

Plugins

Plugins extend the agent’s toolset and behavior. They’re configured in the agent’s settings file (e.g., /home/node/.claude/settings.json for Claude) and loaded at startup.

​

Environment variables

Env vars from your configuration are written to files in /whim/env-files/ and sourced into the container’s shell environment. These are merged across config layers, with later layers overriding earlier ones.

​

Scripts

• Init script (/whim/init.sh) — runs at container startup, before the agent begins. Use it to install dependencies, set up tools, or configure the environment.
• Bashrc (/whim/bashrc) — appended to the container’s .bashrc for shell aliases, PATH modifications, etc.

​

Container services

Several background services run alongside the agent inside every container:

​

Generation proxy (port 3001)

Routes AI model requests through the configured provider. For OpenRouter-backed providers, it proxies requests to OpenRouter’s API. The proxy also:

• Tracks whether the agent is working or idle by monitoring active requests
• Writes agent state to /tmp/claude_state for heartbeat monitoring
• Logs generation IDs for debugging and billing

​

Local proxy (port 8080)

When the agent starts a dev server (e.g., npm run dev on port 3000), the local proxy makes it accessible via a shareable URL. It auto-detects running servers and proxies HTTP and WebSocket traffic from Whim’s external routing layer to localhost inside the container.

​

Port monitor

Detects when new ports open inside the container and registers them with Whim’s router, enabling live preview URLs without manual configuration.

​

Backup agent (port 8081)

Periodically saves the agent’s conversation history and shell history to Whim’s backend. This powers the conversation view in the UI and enables search across all workspace tasks.

​

The Whim MCP server

Every task container includes a built-in MCP server that gives the agent workspace awareness. Through this server, the agent can:

• List and search tasks in the workspace
• Create new tasks and todos to parallelize or plan work
• Send prompts to other running tasks
• Read comments and attachments on tasks
• Inspect workspace configuration and settings
• Manage task lifecycle — pause, resume, complete, archive

This is what enables orchestrator mode — agents coordinating other agents. But even in simple mode, the MCP server is available, so an agent can check what other tasks exist or spawn follow-up work. The MCP server communicates with Whim’s backend API using an internal auth token (WHIM_INTERNAL_API_TOKEN) that’s scoped to the task’s workspace.

​

Agent lifecycle

Here’s what happens from the moment you click Create Task to when the agent finishes:

​

1. Container provisioning

Whim claims a container — either from a warm pool of pre-provisioned machines (fast, typically under 5 seconds) or by creating one on-demand (slightly slower). If your workspace has a custom image, a reserved machine with that image is used.

​

2. Environment setup

The container runs the startup sequence:

1. Clone your repo and check out a new branch from the configured source branch
2. Set up git credentials (GitHub App token for push/pull)
3. Execute the init script (if configured)
4. Source env files and bashrc
5. Restore session state (if this is a resumed or forked task)

​

3. Services start

Background services start in order: backup agent, local proxy, port monitor, generation proxy, and web terminals (for browser-based shell access via tmux + ttyd).

​

4. Agent starts

The AI coding agent launches with:

• Your prompt (passed as the initial message)
• Your instructions (loaded from /app/CLAUDE.md)
• Your skills (available as slash commands)
• Your MCP servers (including the built-in Whim server)
• Your plugins (loaded from settings)

The agent begins working, and its terminal output streams to your browser in real time.

​

5. Working

The agent reads code, writes files, runs commands, and iterates. You can:

• Watch the terminal live
• Send follow-up prompts to steer the agent
• Open additional shell panes alongside the agent
• View live previews of running dev servers

​

6. Idle and auto-sleep

When the agent finishes or goes idle, the container enters a waiting state. After a configurable idle period (default: 15 minutes), the container auto-sleeps to conserve CUs. Sleeping tasks resume instantly when you interact with them.

​

7. Completion

When you mark a task as completed (or the agent completes its work and you confirm), the container is suspended. The git branch, conversation history, and all results are preserved.

​

Provider-specific behavior

While the container environment is consistent across providers, each AI runtime has its own characteristics: