Self-Hosted AI Coding Agent Setup: A Step-by-Step Guide

Published August 10, 2026 · by the AQ team

A self-hosted AI coding agent setup is one Linux VM you control, an agent CLI like Claude Code or Codex, and tmux to keep sessions alive when you disconnect. You can go from a fresh Ubuntu server to a working, persistent agent in under an hour. This guide walks the whole path in order: sizing the VM, locking down access, installing the tooling, authenticating the CLIs on a headless machine (the step that trips up most people), running your first agent task, and keeping it all alive. Still weighing the routes? Read our overview of self-hosted AI coding agent options first; this page is the hands-on companion for its plain-VM route.

Step 1: Size and create the VM

The agent CLI is light: Anthropic lists 4 GB of RAM and an x64 or ARM64 processor for Claude Code, and no GPU is involved, since model inference happens on the provider's side. Your VM runs the CLI, your repository, and your project's toolchain, and that last part is what drives sizing.

Give it 50 to 100 GB of SSD storage: every git worktree carries its own node_modules or build directory, and they accumulate. Any provider works. Pick a recent Ubuntu LTS or Debian; Claude Code supports Ubuntu 20.04 and later and Debian 10 and later, as of August 2026.

Step 2: Lock down access before installing anything

The VM will hold real credentials: your CLI logins and a GitHub token that can push. At minimum, use SSH keys only and disable password authentication in sshd_config. Better, take the VM off the public internet entirely with Tailscale: it gives the machine a private address reachable only from your own devices, and its SSH mode ties access to your identity instead of key files.

# On the VM: install Tailscale and enable SSH over the private network
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh

If you work from trains or hotel wifi, add mosh: it bootstraps over SSH, then runs the session over UDP so it survives IP changes and sleep-and-resume without dropping your terminal.

Step 3: Install the base tooling

You need git, tmux, and your project's toolchain, plus a current Node if you install any agent CLI through npm (the npm builds of both Claude Code and Codex require Node 22 or later, as of August 2026).

sudo apt update
sudo apt install -y git tmux build-essential

# Node 22 (needed for npm installs of the agent CLIs)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Then add whatever your repository needs to build and test. The agent runs the same commands you would, so set the machine up as if a new teammate were joining.

Step 4: Install the agent CLIs

As of August 2026, both major CLIs ship one-line installers. Claude Code's native installer needs no Node at all and auto-updates in the background:

# Claude Code
curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor   # read-only diagnostics: install health, settings problems

# Codex CLI
npm install -g @openai/codex
codex --version

Codex also offers a standalone installer script from chatgpt.com if you prefer to skip Node, and Cursor's terminal agent installs the same way (a curl script from cursor.com; the binary is named agent). They coexist fine, and running two agents on two different tasks is a normal way to use one VM.

Step 5: Authenticate on a headless machine

This is where most setups stall. Both CLIs default to a browser-based OAuth login, and a headless VM has no browser. Each has a supported way through, as of August 2026.

Claude Code requires a Pro, Max, Team, Enterprise, or Console account. Run claude in your SSH session and open the login URL on your laptop. Because the browser cannot reach the callback server on the VM, it shows a login code instead: paste it back into the terminal at the prompt (Anthropic documents this paste-back flow for SSH sessions and containers). The alternative is minting a long-lived token on your laptop and exporting it on the VM:

# On your laptop (has a browser):
claude setup-token   # prints a one-year OAuth token

# On the VM:
export CLAUDE_CODE_OAUTH_TOKEN=paste-the-token-here

Codex CLI signs in with your ChatGPT account. Its login flow listens on localhost port 1455 for the OAuth callback, which fails over plain SSH. Two ways through:

# Option A: tunnel the callback port, then log in inside that session
ssh -L 1455:localhost:1455 you@your-vm
codex login
# open the printed localhost:1455 URL in your laptop browser

# Option B: device-code flow, no tunnel needed
codex login --device-auth

The device-code option shows a short code you enter in a browser on any device; it may need enabling first in ChatGPT security settings, or by a workspace admin on business plans.

Step 6: Connect GitHub with least privilege

The agent commits and pushes as whoever the VM is logged in as, so make that identity real and scoped. The GitHub CLI's device-flow login works fine over SSH:

gh auth login    # choose SSH or HTTPS; device flow works headless
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Prefer fine-grained tokens scoped to the repositories the agent will touch, and keep branch protection on so agent work lands through a pull request. Our guide to running agents safely on your own repos covers the full checklist.

Step 7: The first agent run

Run each task in its own git worktree and its own named tmux session. The worktree keeps parallel tasks from trampling each other's checkouts; tmux keeps the session alive when your connection drops or your laptop closes.

git clone https://github.com/your-org/your-repo.git
cd your-repo

# One worktree per task, on its own branch
git worktree add ../fix-auth -b fix-auth
cd ../fix-auth

# One named tmux session per task
tmux new -s fix-auth
claude          # or codex; work interactively as usual

# Detach with Ctrl-b then d. Close the laptop. Later, from anywhere:
tmux attach -t fix-auth

That detach-and-reattach loop is the entire payoff of self-hosting: the session belongs to the server, not to your terminal window. Our worktrees guide for AI coding agents explains the layout and cleanup.

Step 8: Keep it alive and healthy

A few realities of the long-running setup, worth knowing up front:

• tmux is in-memory. Sessions survive disconnects but not reboots, and unattended upgrades can reboot the box. After a restart, tmux ls is empty.
• Agents pause on permission prompts. An agent waiting for approval at 2 am makes no progress until you reattach, so configure the CLI's permission settings deliberately.
• Logins expire. Claude Code warns at startup a few days ahead; renew with /login when you see it.
• Updates. Claude Code's native install auto-updates in the background. npm installs update manually (npm install -g @openai/codex@latest).

For persistence patterns in depth, see keeping Claude Code running after closing your laptop.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. In this guide's terms, AQ is what the setup above becomes when a team depends on it. Agents run as the same real CLIs (Claude Code, Codex, Cursor Agent, Kimi, Grok, or plain shells) in persistent tmux sessions on your team's VM, streamed live to the browser: sessions survive a closed laptop and resume from any device, and a teammate can open the same workspace and watch the same live session. Typing into someone else's terminal is delegated: the owner approves a control request in one click and keeps their own input.

The per-task discipline from step 7 is built in: every workspace gets its own isolated git worktree (branch ai/{id}-{slug}), dependencies installed automatically, and a one-click rebase onto main. Auth stays per-user as in steps 5 and 6: each engineer logs into the CLIs with their own Claude or OpenAI account (AQ never marks up model usage) and their own GitHub auth, and agents commit, push, and open pull requests that AQ tracks per workspace. Step 8's operational load is what the product absorbs: runner health is visible in the product, the installer runs preflight checks, and aq-runner doctor diagnoses a broken host. There is no shared multi-tenant execution tier; details in security and isolation.

Pricing is two plans. Free is the full product on a VM you bring (exactly the machine this guide had you create; you pay only your cloud provider). Team is $100 per user per month promotional (standard $200, billed monthly) and includes a dedicated always-on AQ-managed VM in its own isolated network, with your rate locked for your first 12 months. There is no blanket free trial, but newly invited teammates are free for their first 14 days.

Plainly: if you are one engineer, the eight steps above are the whole job, and you should just do them. AQ earns its place when the same setup needs to be shared, visible, and boring to operate for a whole team.