> ## Documentation Index
> Fetch the complete documentation index at: https://comis-feature-matrix-channel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Install on a VPS
> Deploy Comis on Hostinger, DigitalOcean, Hetzner, or any Ubuntu VPS in under 10 minutes
This guide walks you through deploying Comis on a fresh VPS (Virtual Private
Server). By the end you will have a running daemon managed by systemd, with your
AI agent reachable through Telegram, Discord, or any supported channel.
The instructions work on **any provider** that gives you an Ubuntu server with
root SSH access -- Hostinger, DigitalOcean, Hetzner, Vultr, Linode, AWS
Lightsail, and others.
You don't need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.
## What you need
Before you start, have these ready:
| Item | Where to get it |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A VPS running **Ubuntu 22.04+** with at least 1 GB RAM | Your hosting provider's dashboard |
| **Root SSH access** to the server | Your provider sends credentials after purchase |
| An **AI provider API key** (Anthropic, OpenAI, or Google) | [Anthropic Console](https://console.anthropic.com), [OpenAI Platform](https://platform.openai.com), or [Google AI Studio](https://aistudio.google.com) |
| A **chat channel bot token** (optional) | See the [Channels](/channels/index) section for setup guides |
Most providers offer an Ubuntu image by default. If you have a choice, pick
**Ubuntu 24.04 LTS** -- it has the best compatibility with Comis.
## Step 1: Connect to your server
Open a terminal on your computer and SSH into your VPS. Replace the IP address
with your server's address.
```bash theme={}
ssh root@your-server-ip
```
Your provider may give you a password or an SSH key. Hostinger, for example,
shows the password in the VPS dashboard under **SSH Access**.
If your provider gives you a password, you will be prompted to enter it after
running the SSH command. You can also set up SSH keys later for passwordless
login.
## Step 2: Install Comis
Run the one-line installer. It handles everything: Node.js, system packages, a
dedicated `comis` user, systemd service, and the Comis package itself.
```bash theme={}
curl -fsSL https://comis.ai/install.sh | bash
```
The installer takes 2-3 minutes. You will see a progress log like this:
```
COMIS Installer
Friendly by nature. Powerful by design.
[1/4] Preparing system (as root)
✓ Node.js v22 installed
✓ System dependencies ready
✓ User 'comis' created
[2/4] Installing Comis
✓ Comis npm package installed
[2/4] Registering daemon as a service
✓ comis.service started
✓ Daemon is responding on the gateway port
Comis installed successfully (1.0.53)!
```
Run the installer as `root` (the standard VPS login). If you run it as a
regular user instead, it asks to re-run itself with `sudo` -- either way it
creates a dedicated `comis` user with restricted permissions and runs the
daemon under that user. This is the secure default; pass `--no-user` only if
you explicitly want the daemon running as your login user.
### Browser tool
The browser tool ships **enabled by default**, so the default install already provisions
Chrome + the headless libs + the headed Xvfb stack (best-effort — see the Linux install
guide's fallback note). You only need a flag to opt out or to switch to the stealth build:
```bash theme={}
# Default install — browser tool + headed stack provisioned best-effort
curl -fsSL https://comis.ai/install.sh | bash
# Minimal footprint — skip the browser runtime entirely
curl -fsSL https://comis.ai/install.sh | bash -s -- --without-browser
# Stealth Chromium — bypasses Cloudflare Turnstile, FingerprintJS,
# BrowserScan, and Reddit's secondary fingerprint check
curl -fsSL https://comis.ai/install.sh | bash -s -- --with-cloakbrowser
```
**VPS providers are pre-blocked by Reddit, X/Twitter, LinkedIn, and many anti-bot services at the IP layer.** Hostinger, DigitalOcean, AWS, Hetzner — all flagged regardless of which browser you run. CloakBrowser does not include a proxy: it fixes browser-fingerprint detection, not IP reputation. If you want Reddit/social scraping from a VPS, pair `--with-cloakbrowser` with a residential proxy. If you only need to hit Cloudflare-protected sites that don't blocklist VPS ranges, the stealth flag alone is enough.
Sites verified bypassed on a Hostinger VPS with `--with-cloakbrowser`: bot.incolumitas.com (1 fail vs 4 for stock Chrome), browserscan.net (`Normal` vs `Robot`). Reddit and X stayed blocked due to IP filtering, not fingerprint detection.
See [agent-tools/browser](/agent-tools/browser#stealth-mode-anti-bot-detection) for the full flag matrix, sandbox details, and license terms (CloakBrowser's binary is free for self-hosted use; OEM license needed for redistributing to third-party customers).
### Optional: DuckDB for SQL/JSONPath result queries
The [`orchestrate`](/agent-tools/orchestrate#resultref-high-volume-returns) tool's
`ResultRef.sql()` / `ResultRef.jsonpath()` helpers run the **DuckDB** CLI
daemon-side to query a high-volume tabular result without re-entering the whole
payload into context. DuckDB is **optional**: if it is absent, `sql`/`jsonpath`
honest-degrade to an `{ error }` and the other extraction methods
(`read`/`grep`/`jq`) keep working.
DuckDB is **not** in the Debian/Ubuntu apt repositories (`apt-get install duckdb`
fails), so fetch the pinned **static binary** from the DuckDB release page and put
it on the daemon's `PATH`:
```bash theme={}
# Fetch the pinned DuckDB static CLI (amd64 shown; use the aarch64 asset on arm64).
curl -fsSL -o /tmp/duckdb.zip \
https://github.com/duckdb/duckdb/releases/download/v1.5.4/duckdb_cli-linux-amd64.zip
sudo unzip -o /tmp/duckdb.zip -d /usr/local/bin && rm /tmp/duckdb.zip
duckdb --version # confirm it is on PATH
```
The official Docker image already provisions this static binary, so containerized
deployments need no extra step. The query surface is hardened to a read-only
slicer (`--readonly :memory:`, extension auto-load off, extension/file-write/network
statements refused before spawn) -- see the
[orchestrate tool reference](/agent-tools/orchestrate#resultref-high-volume-returns).
## Step 3: Switch to the comis user
The daemon runs under its own system user. Switch to it for all Comis commands:
```bash theme={}
su - comis
```
Verify the installation:
```bash theme={}
comis --version
```
Expected output (version number — yours may differ):
```
1.0.53
```
## Step 4: Run the setup wizard
The interactive wizard configures your AI provider, generates a gateway token,
and (optionally) connects a chat channel.
```bash theme={}
comis init
```
The wizard walks you through:
1. **AI Provider** -- choose Anthropic, OpenAI, or Google and paste your API key
2. **Agent name** -- give your agent a personality
3. **Channels** -- connect Telegram, Discord, or others (you can skip and add later)
4. **Gateway security** -- auto-generates an authentication token
5. **Start daemon** -- restarts the daemon with your new configuration
When the wizard asks to restart the daemon, choose **Restart (recommended)**.
This ensures the daemon picks up your API key and gateway token immediately.
### Codex OAuth on headless hosts
If you pick `openai-codex` as your provider on a VPS, the wizard's auto-default for the login method is `Device code (phone)` -- the recommended path on headless hosts. This is because VPS images typically lack a default browser, and SSH sessions usually have no clipboard or scrollback that the browser-paste flow relies on.
The wizard detects headless hosts via standard environment variables:
* `SSH_CLIENT` or `SSH_TTY` set, **or**
* `DISPLAY` unset
When detected, the picker pre-selects `Device code (phone)`. You confirm by pressing Enter; the wizard prints a short code and a verification URL like `https://chat.openai.com/oauth/device`. Open that URL on your phone or laptop browser, sign into ChatGPT, and type the code. The wizard polls every 5 seconds and continues once the code is accepted.
You can re-run the OAuth login at any time, with or without finishing the wizard. From a TTY:
```bash theme={}
comis auth login --provider openai-codex --method device-code
```
This is the same flow the wizard runs and writes to the same OAuth credential store. Use it if you picked `Skip for now` in the wizard or want to add a second ChatGPT account (multi-account is supported -- see [OAuth concepts -> Multi-account profiles](/security/oauth#multi-account-profiles)).
For the wizard's full 4-option picker walkthrough -- including the local-desktop and browser-manual-paste options -- see the [Quickstart](/get-started/quickstart#picking-an-openai-provider-openai-vs-openai-codex). For the OAuth threat model and storage backends, see [OAuth concepts](/security/oauth).
## Step 5: Verify everything works
```bash theme={}
comis status
```
You should see all systems online:
```
Daemon
Status online
Uptime 12s
Gateway
Status online
Address 127.0.0.1:4766
Agents
┌─────────┬───────────┬─────────────────┐
│ Name │ Provider │ Model │
├─────────┼───────────┼─────────────────┤
│ default │ anthropic │ claude-opus-4-6 │
└─────────┴───────────┴─────────────────┘
```
Run the doctor to check for any issues:
```bash theme={}
comis doctor
```
## Managing the daemon
The comis user has full control over the daemon:
```bash theme={}
comis daemon status # Check if running
comis daemon start # Start the daemon
comis daemon stop # Stop the daemon
comis daemon logs # View recent logs
comis daemon logs -f # Follow logs in real-time
```
The daemon runs under systemd and starts automatically on boot. If you ever need
to restart it as root:
```bash theme={}
sudo systemctl restart comis
```
## Common tasks
### Change the AI model
```bash theme={}
comis models list --provider anthropic
comis models set default claude-sonnet-4-6
```
### Add a Telegram bot
1. Create a bot with [@BotFather](https://t.me/BotFather) on Telegram
2. Copy the bot token
3. Run the setup wizard for channels:
```bash theme={}
comis configure --section channels
```
Or edit the config directly:
```bash theme={}
comis config show channels
```
See the [Telegram channel guide](/channels/telegram) for detailed instructions.
### Check memory and sessions
```bash theme={}
comis memory stats # Memory database statistics
comis memory search "topic" # Search stored memories
comis sessions list # List active sessions
```
### Run a security audit
```bash theme={}
comis security audit # Check for security issues
comis secrets audit # Scan for plaintext secrets
```
## Provider-specific notes
Hostinger VPS plans come with Ubuntu and root SSH access by default.
1. In the Hostinger dashboard, go to **VPS** and find your server's IP and password
2. SSH in: `ssh root@your-ip`
3. Run the installer as shown above
Hostinger's KVM plans (starting at 1 GB RAM) work well with Comis. The
installer handles all dependencies automatically.
Create a Droplet with **Ubuntu 24.04**, minimum **1 GB / 1 vCPU**.
1. In the DigitalOcean dashboard, create a new Droplet
2. Choose Ubuntu 24.04 LTS
3. Select the \$6/month plan (1 GB RAM) or higher
4. Add your SSH key or choose password authentication
5. SSH in and run the installer
DigitalOcean Droplets work out of the box -- no extra configuration needed.
Create a server with **Ubuntu 24.04**, minimum **CX22** (2 GB RAM).
1. In the Hetzner Cloud console, create a new server
2. Choose Ubuntu 24.04
3. Select CX22 or higher
4. Add your SSH key
5. SSH in and run the installer
Hetzner offers excellent value for Comis deployments, especially the
ARM-based CAX servers.
Any provider that offers Ubuntu 22.04+ with root access works identically:
1. Create an Ubuntu instance with at least 1 GB RAM
2. SSH in as root
3. Run the one-line installer
The installer auto-detects the environment and handles everything.
## Troubleshooting
Clear the npm cache and retry:
```bash theme={}
npm cache clean --force
curl -fsSL https://comis.ai/install.sh | bash
```
The daemon may need a restart to pick up the new configuration:
```bash theme={}
comis daemon stop
comis daemon start
comis daemon logs --lines 20
```
If the logs show startup errors, check your API key is valid:
```bash theme={}
comis doctor
```
This usually means the gateway token is not loaded. Restart the daemon:
```bash theme={}
comis daemon stop
comis daemon start
```
If that doesn't help, re-run the setup wizard:
```bash theme={}
comis init
```
If you see a permissions error, the sudoers rule may be missing. As root:
```bash theme={}
echo 'comis ALL=(root) NOPASSWD: /usr/bin/systemctl start comis, /usr/bin/systemctl stop comis, /usr/bin/systemctl restart comis' > /etc/sudoers.d/comis
chmod 0440 /etc/sudoers.d/comis
```
Then switch back to the comis user and try again.
Comis uses around 300-500 MB of RAM. If your server has only 1 GB, consider:
* Adding swap space: `fallocate -l 1G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile`
* Upgrading to a 2 GB plan
* Using a smaller model (e.g., `claude-haiku-4-5` instead of `claude-opus-4-6`)
## Uninstalling
To completely remove Comis from the server:
```bash theme={}
# As root
curl -fsSL https://comis.ai/install.sh | bash -s -- --uninstall --remove-user
```
This stops the daemon, removes the systemd service, deletes the comis user, and
cleans up all data.
## Next steps
Add Telegram, Discord, Slack, or other messaging platforms.
Customize your agent's personality, tools, and behavior.
Enable encrypted secrets, TLS, and approval gates.
Logs, metrics, and the web dashboard.