How to Set Up Office Claws: A Complete Step-by-Step Guide

How to Set Up Office Claws: A Complete Step-by-Step Guide — Set up Office Claws and deploy a secure AI agent on your own Contabo VPS in minutes: CLI install, subscription, Contabo and Tailscale credentials, provisioning, connecting Codex, and the security layers Office Claws automates.
Apr 15, 202614 mins read
Share with

Managing AI agents usually means wrestling with terminal windows, SSH sessions, and scattered configuration files. Office Claws replaces all of that with one CLI — plus a desktop app with a pixel-art office where each agent sits at their own desk. Every agent runs on a VPS in your own Contabo account and talks to your computer over your own Tailscale network. This guide walks you through every step of the setup — from installing the CLI to chatting with your first agent.

What You Need Before You Start

Gather the following before you begin. Having everything ready keeps the setup to a few minutes.

Accounts and Credentials

  • An Office Claws subscription. There is one plan, Self-Hosted, at $4.99/month. An active subscription is required before you can provision an agent — you subscribe from the CLI in Step 2.
  • A Contabo account with a VPS. Your agent runs on a VPS in your own Contabo account, and you pay Contabo directly for it — a small VPS costs a few euros a month. Order the VPS in Contabo before you start onboarding. Office Claws runs one agent per VPS.
  • Contabo API credentials. Open my.contabo.com/api/details and note your Client ID and Client secret (under "API Data"), your API user (your Contabo login email), and your API password. The API password is not your website login password — if you have never set one, click "Set password" on that page.
  • A Tailscale account and auth key. Tailscale creates the encrypted network between your computer and your agent's VPS. Create a free account at tailscale.com, then generate an auth key in the admin console under Settings > Keys > Generate auth key.
  • A ChatGPT subscription with Codex. Your agent runs on your own OpenAI Codex (ChatGPT) subscription, which you connect with a browser sign-in in Step 5. No API key is needed.
  • A computer running macOS or Linux, with Tailscale installed and connected. The CLI reaches your agents over your tailnet.

Run your first agent in about 3 minutes

Install the Office Claws CLI, connect your Contabo account and Codex subscription, and your agent gets its own VPS and a desk in the office.

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/mo + your own Contabo VPS · keys stay in your keychain

How Pricing Works

Office Claws has a single plan: Self-Hosted, $4.99/month. It includes the CLI, the desktop app with its pixel-art office, real-time agent chat, logs, scheduled jobs, and channels such as Telegram. The infrastructure stays yours: the VPS lives in your Contabo account and is billed by Contabo, and the model runs on your own Codex subscription.

There is no free trial — an active subscription is required before provisioning. Refunds are covered by our Refund Policy.

Setup flow: Download, Register, Configure, Provision, Chat

Step 1: Install the CLI

Install the officeclaws CLI with one command:

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

Run officeclaws version to confirm it is on your PATH. Prefer a graphical interface? The desktop app with the pixel-art office is available from the homepage and works with the same account and agents.

Step 2: Create Your Account and Subscribe

officeclaws register    # or: officeclaws login
officeclaws subscribe

register creates your Office Claws account with an email and password; use login if you already have one. subscribe opens the checkout in your browser (if it cannot open a browser, it prints the link to copy). Once the payment goes through, your account is ready to provision agents.

Step 3: Onboard Your First Agent

officeclaws onboard --name Mona

Onboarding is interactive. It:

  1. Checks that your subscription is active. If it is not, it points you back to officeclaws subscribe.
  2. Asks for your four Contabo API credentials and validates them. They are saved in your OS keychain, so you enter them only once.
  3. Asks for your Tailscale auth key, which is also saved in the keychain.
  4. Creates an SSH key that the CLI uses to reach your agents.
  5. Syncs the VPSes in your Contabo account and lets you pick the one to turn into an agent.

If you leave out --name, onboarding prompts for it. Two optional flags personalize the agent: --comm-style friendly|business|creative sets its tone, and --avatar picks one of the 12 pixel-art avatars shown in the desktop office. Every prompt also has a flag (--contabo-client-id, --tailscale-authkey, --vps, and so on), so onboarding can run fully non-interactively — officeclaws help lists them all.

Step 4: Watch Provisioning

After you pick a VPS, Office Claws provisions it and streams progress straight to your terminal as it:

  1. Installs the agent from a pre-built Office Claws image.
  2. Joins the VPS to your Tailscale network.
  3. Hardens the server and starts the agent runtime in Docker.
  4. Sets up the agent gateway, reachable only over your tailnet.

The whole process takes about 2 to 3 minutes. The image is pre-baked with everything the agent needs, so the server does not install packages from scratch — that is what keeps provisioning fast. When it finishes, the CLI prints your next two commands.

If the VPS already holds data you want to replace, --reinstall wipes it and reinstalls it from the Office Claws image. Use it only on a server you are happy to erase.

Step 5: Connect Your Codex Subscription

officeclaws connect-codex

This opens OpenAI's sign-in page in your browser (or prints the link). Sign in with the ChatGPT account that has Codex; the CLI waits for you to finish (up to five minutes) and confirms when your agent is running on your subscription. Codex is the supported model path for Office Claws agents — Claude Code and other Anthropic subscriptions are not supported.

Step 6: Start Chatting with Your Agent

officeclaws chat

This opens an interactive chat with your primary agent (press Ctrl-D to exit). Use officeclaws chat -m "..." for a one-shot message, --agent <id> to talk to a specific agent, officeclaws agents to list your agents, and officeclaws logs --follow to stream an agent's logs.

Try these first messages to test your setup:

  • "What can you help me with?"
  • "Summarize this document for me: [paste text]"
  • "Review this code for bugs: [paste code]"

In the desktop app, the same agent appears at a desk in the pixel-art office — click its sprite to open the chat panel, which keeps the full message history so you can pick up where you left off.

Understanding the Pixel-Art Office

If you use the desktop app, the office is more than a visual gimmick. It gives you an at-a-glance status overview of all your agents:

Agent states: Typing, Coffee, Resting, Offline

  • Typing at a desk — The agent is actively processing or available.
  • Grabbing coffee — The agent is in a brief idle cycle.
  • Resting on the sofa — The agent is in a longer idle state.
  • Sitting in the offline area — The agent's VPS is unreachable.

As you add more agents, each one gets assigned to a desk in the office. The layout supports up to six desks in the main room, a desk in the side office, and lounge seating in the break areas.

How Your Credentials Stay Secure

Security is a common concern when a tool touches your cloud and AI accounts. Here is how Office Claws handles it:

  1. Local keychain storage. Your Contabo API credentials, Tailscale auth key, and CLI session are stored in your operating system's keychain, not on Office Claws servers. Secret values are never printed — credential listings show only masked previews.
  2. Your own network. The CLI and desktop app reach your agent over SSH through your Tailscale network. The agent's SSH, HTTPS, and gateway ports are open only on your tailnet.
  3. Your own subscription. Connecting Codex uses OpenAI's sign-in flow: you log in on OpenAI's page, and no API key is copied around. The resulting login lives on your agent's VPS.
  4. Direct connection. Chat and logs travel directly between your computer and your agent over your tailnet. Once you run officeclaws connect-codex, model requests go from your agent's VPS straight to OpenAI; before that, a small starter allowance runs through the Office Claws LLM gateway. Office Claws does keep a copy of your chat history in your account; the security page lists exactly what is stored.

What Office Claws Automates: The Manual Setup You Skip

To understand the value of one-command provisioning, it helps to see what setting up a secure AI agent VPS looks like without it. Below is every step Office Claws handles automatically behind the scenes. If you were doing this yourself, plan for 45 minutes to an hour of terminal work per server — assuming you get every command right on the first try.

Create and Access the Server

Manually, you would log into your cloud provider (Contabo, Hetzner, DigitalOcean, or another), create an Ubuntu 24.04 server, wait for it to boot, and SSH in as root. You also need to generate an SSH key pair, upload the public key, and confirm you can connect.

Create a Non-Root User

Running services as root is a security risk. You would need to create a dedicated user, add it to the sudo group, copy your SSH public key into its authorized_keys file, and set correct file permissions (700 for the .ssh directory, 600 for the key file). Then configure passwordless sudo access for specific commands — firewall, Tailscale, and Docker — so the agent process can manage those services without full root privileges.

Harden SSH

Out of the box, SSH on a fresh Ubuntu server allows root login and password authentication — both are common attack vectors. You need to write a hardening configuration that disables all of these:

  • Root login (PermitRootLogin no)
  • Password authentication (PasswordAuthentication no)
  • Challenge-response authentication
  • X11 forwarding
  • Agent forwarding

Then validate the config syntax with sshd -t and restart the SSH service. One typo in this file and you lock yourself out of the server.

Install and Configure the Firewall

Next, install ufw (Uncomplicated Firewall) and set a deny-all-incoming default policy. You temporarily allow SSH on all interfaces so you don't lose your connection, then later — after Tailscale is running — you restrict SSH, HTTPS, and the agent gateway port (18789) to the Tailscale interface only and delete the public SSH rule. The final firewall state:

  • All incoming traffic denied by default
  • Port 22 (SSH): allowed only over Tailscale
  • Port 443 (HTTPS): allowed only over Tailscale
  • Port 18789 (agent gateway): allowed only over Tailscale
  • All outgoing traffic allowed

Getting the order of operations wrong here — restricting SSH before Tailscale is up — means losing access to the server entirely.

Set Up Intrusion Prevention

Install and enable fail2ban, which monitors authentication logs and temporarily bans IP addresses that show brute-force login patterns. This adds a layer of defense even if SSH is eventually exposed through a misconfiguration.

Enable Automatic Security Updates

Install unattended-upgrades and apt-listchanges, then configure them with dpkg-reconfigure. This ensures the server applies security patches automatically without manual intervention. Skipping this step means your server falls behind on patches within weeks.

Allocate Swap Memory

Create a 2 GB swapfile at /swapfile, set permissions to 600, format it with mkswap, activate it with swapon, and add it to /etc/fstab so it persists across reboots. Without swap, a memory spike in the agent process can kill the container or crash the server.

Install and Configure Tailscale

Install Tailscale from their official install script, bring it up with your auth key and a hostname, wait for an IP assignment (up to 60 seconds), set the operator to your non-root user, request a TLS certificate, and enable HTTPS serving on the agent gateway port. This creates the encrypted tunnel that replaces public internet exposure for all agent communication.

Install Docker and Pull the Agent Image

Install Docker from the official install script, add your non-root user to the docker group, authenticate with the container registry if needed, and pre-pull the agent runtime image. Then launch the container with the correct environment variables, memory limits (1800 MB with 2 GB swap), host networking, a persistent volume, and a restart policy so it survives reboots.

Connect the Model Provider

Configure the agent's model access — an API key passed into the container as an environment variable, or a subscription sign-in such as Codex — and set up the gateway with WebSocket connectivity, TLS, and operator permissions. Then wait for the gateway to initialize and extract the authentication token from the container logs.

Verify Everything Works

Confirm that the firewall rules are correct, Tailscale is connected, the Docker container is running, the agent responds through the gateway, and your local machine can reach it through the Tailscale network. Update your local SSH config and known_hosts for convenient access later.

What This Adds Up To

Here is the full list of packages and services configured on every Office Claws agent VPS:

All 8 security layers automated by Office Claws

ComponentPurpose
ufwFirewall with Tailscale-only access rules
fail2banBrute-force intrusion prevention
unattended-upgradesAutomatic security patches
SSH hardening configDisables root login, passwords, forwarding
TailscaleEncrypted networking and TLS certificates
DockerContainerized agent runtime with memory limits
2 GB swapMemory overflow protection
Non-root user with scoped sudoPrinciple of least privilege

That is eight security layers configured across roughly 20 manual steps, each with its own failure modes. Miss the firewall order and you lock yourself out. Forget swap and the agent crashes under load. Skip unattended-upgrades and your server accumulates vulnerabilities. Misconfigure SSH hardening and you leave the door open — or shut it on yourself.

With Office Claws, you run officeclaws onboard, watch the progress stream for two or three minutes, and get all of it — hardened, tested, and connected. Image-based provisioning means every server starts from a pre-built, verified image, so there is zero drift between what you expect and what you get.

Troubleshooting Common Setup Issues

"No active subscription"

Onboarding stops if your account has no active subscription. Run officeclaws subscribe, complete the checkout, then re-run officeclaws onboard.

Contabo credentials are rejected

Double-check all four values on my.contabo.com/api/details. The most common mistake is entering your website login password instead of the API password. If you have never set an API password, set one on that page first.

"No VPSes found on your account"

Onboarding turns a VPS that already exists in your Contabo account into an agent. Order a VPS in Contabo, wait until it is running, then re-run officeclaws onboard.

Provisioning takes longer than expected

Provisioning usually takes 2 to 3 minutes. If it is much slower, Contabo may still be setting up the server — check its status in the Contabo control panel. A --reinstall run takes longer because Contabo has to reimage the server first. If provisioning fails, the CLI prints the error, officeclaws agents shows the agent's status, and the full logs are in ~/.openclaw/logs.

Tailscale auth key is rejected

Make sure the key has not expired and, if it is a single-use key, that it has not been used already. Generate a new one in the Tailscale admin console and pass it with officeclaws onboard --tailscale-authkey <key>.

Agent appears offline or chat cannot connect

Verify that Tailscale is running on your computer. chat and logs reach the agent over your tailnet, so both sides need to be connected. Open the Tailscale app and confirm your machine shows as "Connected."

What Comes Next

Once your first agent is up and running:

  • Add more agents. Each agent gets its own VPS and its own desk in the office. Order another VPS in Contabo and run officeclaws onboard again.
  • Schedule recurring work. officeclaws cron add sets up scheduled jobs, and officeclaws telegram set lets you talk to an agent from Telegram.
  • Explore agent personas. Different --comm-style settings produce noticeably different interaction patterns.

Setting up Office Claws takes a few minutes, but the result is a persistent AI workspace that keeps running whether your terminal or the app is open or not. Your agents keep working on their VPS, and you reconnect whenever you need them.

Author

Office Claws Team

Building the future of AI agent management at Office Claws. Sharing insights on infrastructure, security, and developer experience.

Run your first agent in about 3 minutes

Install the Office Claws CLI, connect your Contabo account and Codex subscription, and your agent gets its own VPS and a desk in the office.

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/mo + your own Contabo VPS · keys stay in your keychain