Workspace Servers

AgenticKode executes all task work on remote workspace servers via SSH. This keeps AI agent execution isolated from the main application and allows scaling across multiple machines.

Architecture

AgenticKode (backend/worker)
    │
    ├── SSH → Workspace Server A
    │         ├── Worker user (non-root)
    │         ├── Claude CLI agent
    │         └── Cloned repositories
    │
    └── SSH → Workspace Server B
              ├── Worker user (non-root)
              ├── Ollama agent
              └── Cloned repositories

All workspace operations go through the SSHService. The worker never uses local subprocess calls for task execution.

Adding a Server

Navigate to Workspace Servers and click Add Server.

Field	Description
Name	Display name for the server
Host	IP address or hostname
Port	SSH port (default: `22`)
SSH Key	Select an existing key pair or generate one

SSH Key Management

Manage SSH key pairs from Settings > SSH Keys:

Generate a new key pair — AgenticKode creates an Ed25519 key
Import an existing private key
Deploy the public key to a server

The public key must be added to the server's ~/.ssh/authorized_keys for the user AgenticKode connects as (typically root for initial setup).

Testing and Setup

After adding a server:

Test Connection — Verifies SSH access and basic connectivity
Setup — Runs the automated setup process:
- Installs required system packages
- Creates the worker user (non-root)
- Configures the worker user's SSH access
- Discovers installed AI agents
- Reports setup progress in real time

Worker User Isolation

AgenticKode creates a dedicated non-root user (agentickode-worker by default) on each workspace server:

Task execution runs under this user, not root
The worker user has access only to its home directory and cloned repositories
SSH keys are configured so the worker user can access git remotes
AI agent binaries are copied to the worker user's path

Git Access for Worker User

The worker user needs SSH access to your git repositories. From the server's Git Access panel:

Deploy a git-specific SSH key for the worker user
The key is added to the worker user's ~/.ssh/ directory
Configure the key in your git provider (GitHub deploy keys, GitLab SSH keys, etc.)
Test git access with the Verify button

Agent Discovery and Installation

AgenticKode automatically discovers which AI agents are available on each server.

Discovery

The agent discovery service checks for:

Claude CLI — Looks for the claude binary in standard paths
Codex CLI — Looks for codex in $HOME/.local/bin and standard paths
OpenCode — Looks for opencode in $HOME/.local/bin and standard paths
Ollama — Optional; checks for a running Ollama server URL

Discovery results appear on the server's Agents tab.

Auto-Installation

When a run starts, the ensure_agent_ready() helper in the worker pipeline:

Checks if the required agent is installed on the workspace server
If missing, installs it automatically:
- Claude CLI: Copies the binary from the host, resolving symlinks with readlink -f to get the real 225MB ELF binary
- Sets up the worker user's environment with the agent binary
Verifies the agent is functional with check_status()

You can also manually trigger agent installation from the Agent Management panel on the server page.

Manual Agent Sync

From the server's management panel:

Install — Push an agent to the server
Sync — Update agent binaries to the latest version
Check Status — Verify agent availability without modifying anything

Project Discovery

AgenticKode can discover repositories already cloned on a workspace server. The Projects tab on the server page shows:

Repositories found in the worker user's workspace directory
Their git remote URLs
Whether they match a configured AgenticKode project

Multiple Servers

You can add multiple workspace servers for:

Load distribution — Spread runs across machines
Agent specialization — GPU server for Ollama, CPU server for Claude CLI
Environment isolation — Different servers for different projects or teams

When creating a run, select which workspace server to use. Workflow templates can also specify a preferred server.

Server Requirements

Minimum

Linux (Ubuntu 20.04+ or Debian 11+ recommended)
SSH server running
2 GB RAM
10 GB disk space
Internet access for git operations

Network

SSH port accessible from the AgenticKode host
Outbound HTTPS for git provider APIs
Outbound HTTPS for AI provider APIs (if running Claude CLI directly)

Troubleshooting

Connection Failed

Verify the server is reachable: ssh -p PORT user@host
Check that the SSH public key is in authorized_keys
Ensure the SSH port is not blocked by a firewall

Setup Fails

Check that the connecting user has sudo/root privileges for initial setup
Review setup logs in the real-time progress display
Verify internet access on the server for package installation

Agent Not Found

Run agent discovery from the server's Agents tab
For Claude CLI: verify the binary exists and is executable
For Ollama: verify the Ollama server is running and accessible
Check the worker user's PATH includes the agent binary location

Per-project and per-step overrides (v0.5.1)

Three knobs let you tailor the workspace per project or per step:

Absolute path to an existing local git checkout. When set, workflows skip clone/fetch entirely and operate on that folder. The working tree must be clean — uncommitted changes block the run before any side-effect with a LocalPathError. Worktree isolation is auto-forced so concurrent runs on the same project don't collide.

Useful when you're running AgenticKode against your dev machine and want the agent to work on the repo you already have checked out (matching UID/file ownership, etc.).

Worker Pipeline — How tasks execute on workspace servers
Quick Start — End-to-end walkthrough of creating a run
Configuration — Agent and server configuration reference