Self-Hosted Installation

Install Agent Studio on your own server. Everything runs locally — your code never leaves your infrastructure.

System Requirements

Component	Minimum	Recommended
OS	Ubuntu 22.04 / Debian 12 / AlmaLinux 8+ / Rocky 8+ / RHEL 8+	Ubuntu 24.04 LTS
CPU	2 cores (x64)	4+ cores
RAM	4 GB	8+ GB
Disk	20 GB free	50+ GB SSD
Network	Outbound HTTPS	Static IP + domain
Claude CLI	Anthropic Claude Code (`claude login`)

Quick Install

One command installs everything: PostgreSQL, Redis, Node.js, nginx, and all Agent Studio services.

Step 1: Generate an install token from the portal

# Get your token at https://agentina.digcub-lab.com/portal/install
# Then run:

Step 2: Run the installer

curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/studio.sh | \
  AGENTINA_TOKEN=act_YOUR_TOKEN \
  sudo -E bash

What Gets Installed

PostgreSQL 16 — task database, project metadata
Redis — job queue, real-time streaming
Controller — API server, task orchestration
Executor — spawns Claude sessions, runs tasks
Guard — license enforcement, heartbeat
UI — Next.js dashboard (port 9802)
nginx — reverse proxy (port 9800, configurable)
systemd — auto-start on boot, restart on failure

Architecture


Your Server
├── nginx (port 9800) ── reverse proxy
│   ├── /api/*  → Controller (9801)
│   ├── /ws/*   → Controller (9801) WebSocket
│   └── /*      → UI (9802)
│
├── Controller (9801) ── API, orchestration
├── Executor ── Claude sessions, task execution
├── Guard (9803) ── license, heartbeat to cloud
├── UI (9802) ── Next.js dashboard
│
├── PostgreSQL (system) ── database
├── Redis (9810) ── dedicated job queue
│
└── /var/lib/agentina-studio/ ── state, license, keys

All ports are configurable via environment variables.
Does NOT conflict with other services on ports 80, 443, 3000, 5432, 6379.

The only external connection is the Guard → Control Plane heartbeat (HTTPS, every 60s). All code execution happens locally on your server.

Claude CLI Setup

After installation, set up Claude Code on the server:

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Authenticate
claude login

# Verify
claude --version

Open http://your-server-ip:9800 in your browser
Create your admin account
Create a project pointing to your repository
Run your first task

Port Reference

Service	Default Port	Env Override	Notes
nginx (public)	9800	AGENTINA_HTTP_PORT	Customer-facing dashboard
Controller	9801	AGENTINA_CONTROLLER_PORT	localhost only
UI	9802	AGENTINA_UI_PORT	localhost only
Guard	9803	AGENTINA_GUARD_PORT	localhost only
Redis	9810	AGENTINA_REDIS_PORT	Dedicated instance
PostgreSQL	5432	—	Uses system PostgreSQL

All ports are chosen to avoid conflicts with common services (80, 443, 3000, 5432, 6379, 8080). Safe to install alongside existing applications.

Service Management

# Status
systemctl status agentina-controller
systemctl status agentina-executor
systemctl status agentina-guard
systemctl status agentina-ui

# Logs
journalctl -u agentina-controller -f
journalctl -u agentina-executor -f

# Restart
systemctl restart agentina-controller
systemctl restart agentina-executor

Upgrading

curl -fsSL https://dl.agentina.digcub-lab.com/v1/dist/installer/studio.sh | \
  sudo -E bash -s -- --upgrade

Upgrades preserve your database, license, and configuration. Only the runtime binaries are replaced.

Troubleshooting

Service won't start

Check logs: journalctl -u agentina-controller -n 50. Common causes: PostgreSQL not running, Redis not running, missing environment variables.

Tasks fail with "claude not found"

Install Claude CLI: npm install -g @anthropic-ai/claude-code && claude login

License expired

Contact support to renew. The dashboard remains readable; only task execution is paused.

Can't connect to dashboard

Check nginx: nginx -t && systemctl status nginx. Ensure port 9800 is open in your firewall (ufw allow 9800).

Files module — "Permission denied" when creating folders

The controller needs a writable workspace directory. Fresh installs (v0.2.0+) set this up automatically. If upgrading from an older version, run:

sudo mkdir -p /home/agentina
sudo chown -R agentina:agentina /home/agentina
echo 'FILES_ROOT=/home/agentina' | sudo tee -a /etc/agentina/studio.env
sudo systemctl restart agentina-controller

Controller won't start — ADMIN_PASSWORD not set

Since v0.1.1 the controller requires ADMIN_PASSWORD in the environment. Set it in /etc/agentina/studio.env and restart:

echo 'ADMIN_PASSWORD=your-secure-password' >> /etc/agentina/studio.env
systemctl restart agentina-controller

Fresh installs (v0.1.1+) generate this automatically. Only needed if upgrading from v0.1.0.

Security

All runtime bundles are obfuscated and integrity-verified at startup. The license guard runs independently and enforces machine binding, signed grace state, and tamper detection. See the security page for details.

Uninstall

systemctl stop agentina-guard agentina-controller agentina-executor agentina-ui
systemctl disable agentina-guard agentina-controller agentina-executor agentina-ui
rm /etc/systemd/system/agentina-*.service
systemctl daemon-reload
rm -rf /opt/agentina-studio
# Optionally: rm -rf /var/lib/agentina /etc/agentina