Deutsch
VPS plan
Virtarix S / Starter VPS Includes 3 CPU cores, 6 GB RAM, 50 GB NVMe storage, Unlimited bandwidth*, 1 free snapshot, 1 backup included, IPv4 + IPv6, Full root access,
How to Self-Host PicoClaw on a VPS
This guide explains how to self-host PicoClaw on a VPS so the runtime can live in a persistent remote environment instead of depending on a local machine. Virtarix provides the VPS infrastructure. You install, configure, secure, update, and operate the software you run on it. You bring your own PicoClaw setup, provider access, API keys, repositories, tools, updates, and configuration.
20% welcome offer
$4.40/mo for first 3 months (then $5.50)
PicoClaw Control Panel
Runtime Ready
root@picoclaw-vps:~$ picoclaw gateway --runtime --logs
> ✓ PicoClaw runtime ready. Gateway logs active.
PicoClaw Ready
PicoClaw Runtime Lightweight agent
Binary/Source Path Install choice
Gateway Logs Live output
Provider Config Model access
Protected Keys Private files
Resource Check CPU/RAM/disk
tmux Session Resume shell
Snapshot Safety Rollback ready
Recommended Quick Setup
Use this path when you want the shortest practical route from VPS order to a usable PicoClaw server workspace. The full checklist below expands each step. Start small, verify the selected PicoClaw release path, keep the gateway private during testing, and scale only after measuring real server usage.
Who This Guide Is For
This page is for users who want PicoClaw to run from a small, controlled VPS environment instead of experimenting only on a local machine.
Users testing lightweight agent runtimes
Use a VPS when a small always-on environment is enough but uptime, SSH access, and logs still matter.
Builders who prefer a small server footprint
Keep dependencies, environment files, repositories, and process supervision lean while preserving a remote runtime.
Operators who want logs and state on a server
Move runtime output, configuration, credentials, and restart notes into a dedicated server context.
Technical users comfortable reviewing early-stage framework notes
Virtarix provides the VPS infrastructure. You install, configure, secure, update, and operate the software you run on it.
What You Need Before You Start
Before selecting a plan or installing PicoClaw, confirm the server access, runtime path, credentials, firewall exposure, and recovery routine needed for the deployment.
Use a Linux VPS supported by the PicoClaw release or deployment path you choose, with SSH access and root or sudo access ready.
Have basic terminal knowledge, Git, and the package managers required by the selected PicoClaw installation path.
Install Docker and Docker Compose only for the documented PicoClaw Docker path; add Go, Node.js, or pnpm only when the source or launcher path requires them.
Prepare your own API keys, provider accounts, model access, repositories, and configuration before connecting the runtime. Use official PicoClaw sources rather than third-party packages, domains, or token/crypto claims.
Set a domain, reverse proxy, SSH tunnel, and firewall rules only for interfaces or webhooks you intentionally expose; take backups or snapshots before production-style changes.
Choose the PicoClaw Runtime Path
Before running commands, decide how PicoClaw should be installed, updated, restarted, and recovered on the VPS. Use current upstream documentation as the authority for exact versions, flags, release assets, checksums, and production-suitability notes. Prefer stable releases for a baseline VPS deployment; use nightly or pre-release builds only when you intentionally accept instability and have a rollback snapshot.
Recommended VPS Requirements
Minimum starting point for a test environment:
Recommended Architecture
The VPS is the runtime layer. You connect over SSH, configure PicoClaw, and control logs, state, and access. Virtarix does not supply model keys or operate the PicoClaw layer.
You (Operator)
You connect over SSH and control the full workflow, configuration, security, and updates.
Virtarix VPS
Provides the persistent server with storage, networking, root access, snapshots, and backups.
PicoClaw Runtime
PicoClaw runtime layer and processes running on the VPS.
External Services
API and model providers, repositories, tools, and integrations that you connect and manage.
Step-by-Step Setup Flow
Follow this sequence as a practical deployment checklist, but confirm PicoClaw-specific versions, installer flags, service commands, checksums, and security notes against current official documentation before production-style use.
Prepare the VPS, connect over SSH, and create a clean workspace before installing PicoClaw-specific dependencies.
Choose Ubuntu, Debian, or another Linux distribution supported by the PicoClaw release and install path you select. The package commands below are Debian/Ubuntu examples. Select the location closest to the user, app, API provider, or team where practical, and start with enough CPU, RAM, and storage for persistent background work.
Connect to the VPS over SSH using the server IP and the approved root or bootstrap login.
ssh root@YOUR_SERVER_IPUpdate package metadata and apply security updates before installing PicoClaw dependencies.
sudo apt update
sudo apt upgrade -yCreate a dedicated non-root deployment user for day-to-day project work, then verify that user can connect by SSH and run sudo before disabling root or password login. Reconnect as the deployment user before installing or configuring the agent when your selected runtime path stores user-scoped configuration.
# Create a dedicated non-root user for day-to-day project work
adduser deploy
usermod -aG sudo deployCreate one directory tree for PicoClaw config examples, working files, logs, and backups. Keep secrets out of shell history and commit only templates, not real keys.
APP_HOME="$HOME/self-host-picoclaw-on-vps-runtime"
mkdir -p "$APP_HOME/config" "$APP_HOME/workspace" "$APP_HOME/logs" "$APP_HOME/backups"
chmod 700 "$APP_HOME" "$APP_HOME/config" "$APP_HOME/workspace" "$APP_HOME/logs" "$APP_HOME/backups"
printf '%s\n' "# copy the official template, then add real provider keys privately" > "$APP_HOME/config/env.example"
chmod 600 "$APP_HOME/config/env.example"Install base packages, confirm the current stable release and VPS architecture, follow the selected upstream install path, and configure runtime settings.
Install the baseline packages needed for downloads, Git workflows, certificates, and archive handling.
sudo apt install -y git curl wget unzip ca-certificates gnupgThe official PicoClaw repository describes PicoClaw as a Go-based project, and the installation docs list Go 1.21+ for source builds. For Web UI builds, confirm the current Go, Node.js, and pnpm requirements before installing build tooling on the VPS. If you use the precompiled binary path, keep the server dependencies minimal and avoid installing unnecessary build tools.
Use the latest stable release unless you intentionally need a nightly or pre-release build. Match the release asset to the VPS CPU architecture before downloading.
uname -m
# x86_64 -> picoclaw_Linux_x86_64.tar.gz
# aarch64 -> picoclaw_Linux_arm64.tar.gzUse the official PicoClaw download, release, source, or documented container path you selected. Match the release asset to the VPS CPU architecture, avoid unofficial mirrors, and compare checksums when provided.
# Option A: precompiled x86_64 Linux binary example only.
# Choose the matching release asset for your VPS architecture.
PICOCLAW_ASSET="picoclaw_Linux_x86_64.tar.gz"
curl -fL "https://github.com/sipeed/picoclaw/releases/latest/download/${PICOCLAW_ASSET}" -o "${PICOCLAW_ASSET}"
tar -xzf "${PICOCLAW_ASSET}"
chmod +x ./picoclaw
./picoclaw version
./picoclaw onboard
# Option B: source build path for development or auditing.
# Run these only if you selected the source path.
# git clone https://github.com/sipeed/picoclaw.git
# cd picoclaw
# make deps
# make build
# For launcher/Web UI builds, also follow current upstream frontend steps,
# such as installing web/frontend dependencies and running make build-launcher.Use the configuration files created by onboarding as the authority. Keep provider keys and channel credentials in the security/configuration files expected by the current release.
# If you installed PicoClaw into PATH, use picoclaw instead of ./picoclaw
./picoclaw onboard
# Or initialize with credential encryption where it fits your workflow
# ./picoclaw onboard --enc
nano ~/.picoclaw/config.json
./picoclaw statusStart with the command path you verified during onboarding. Keep gateway or Web UI access local while testing, then expose only after reviewing authentication and firewall rules.
# If you installed PicoClaw into PATH, use picoclaw instead of ./picoclaw
./picoclaw agent -m "test runtime"
./picoclaw agent
./picoclaw gatewayKeep the selected PicoClaw runtime observable, lock down access, test the setup, and plan ongoing maintenance.
Use the process-management path that matches the deployment you selected, and place only the reviewed PicoClaw command behind systemd, supervisor, tmux, Docker Compose, or another controlled manager.
# Binary or source path: verify the command before adding service supervision
./picoclaw status
./picoclaw gateway
# Docker path from the official installation docs.
# Run these only if you selected the Docker path.
# git clone https://github.com/sipeed/picoclaw.git
# cd picoclaw
# docker compose -f docker/docker-compose.yml --profile gateway up
# vim docker/data/config.json
# docker compose -f docker/docker-compose.yml --profile gateway up -d
# docker compose -f docker/docker-compose.yml logs -f picoclaw-gatewayUse SSH keys where possible, restrict password login if appropriate, enable a firewall, expose only the ports PicoClaw actually needs, and protect PicoClaw config/security files.
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verboseConfirm PicoClaw starts, inspect logs, test provider authentication, test any webhook or interface the setup uses, restart the VPS, and confirm the service returns cleanly.
./picoclaw status
df -h
free -h
ss -tulpnReview PicoClaw logs, rotate keys when needed, monitor disk usage, monitor RAM and CPU usage, update framework dependencies, snapshot before upgrades, and keep rollback notes. Re-check upstream release notes before every major update, especially while PicoClaw remains before v1.0.
Why PicoClaw Benefits from a VPS
PicoClaw is positioned as lightweight, but a small footprint still benefits from server uptime, SSH access, logs, secure configuration files, and a controlled place to run background work.
Lightweight always-on runtime
Keep PicoClaw available on a small server without tying background work to a local desktop session.
Minimal dependency surface
Use a narrow VPS setup with only the packages, ports, repositories, and credentials the experiment actually needs.
Server-side logs and rollback notes
Keep process output, failed starts, update notes, environment files, and rollback steps in one place.
Early-stage caution
Keep the first server narrow: one user, one small set of integrations, a firewall, limited ports, and clear logs. Upstream notes describe PicoClaw as early rapid development and warn against production deployment before v1.0, so keep production-suitability language aligned with current official documentation.
Security Basics for PicoClaw on a VPS
Use SSH keys where possible.
Keep root login limited or disabled after a sudo user is ready.
Use a non-root user where practical.
Restrict ports and keep gateway/Web UI access private until deliberately exposed.
Store provider keys, channel tokens, and gateway secrets in the PicoClaw configuration or security-file path expected by the selected deployment mode.
Avoid committing real PicoClaw config, security files, provider keys, or channel credentials.
Review SSH logs, gateway access, exposed Web UI routes, messaging-channel access, provider-key usage, and changes to PicoClaw configuration files.
Keep packages updated.
Snapshot before major PicoClaw changes.
Monitor failed login attempts.
Rotate exposed keys.
Keep experiments separate from production systems.
Privileged runtime
The server can contain binaries, config files, gateway experiments, credentials, logs, and release-change notes. Harden it before any production-style use.
Troubleshooting
Common setup problems to check before blaming the VPS or framework.
Server firewall, wrong IP, or SSH service unavailable Confirm the VPS is running, check the IP, and verify port 22 or your configured SSH port.
Wrong key, wrong user, or disabled login method
Check ~/.ssh/authorized_keys, user permissions, and your SSH config.
Base packages or runtime packages were not installed Re-run the dependency step and compare runtime versions with official PicoClaw docs.
The selected PicoClaw build path expects a different runtime version Use the version manager or package source recommended by upstream docs.
Docker daemon stopped or not installed This only applies if you selected the PicoClaw Docker path; start Docker and inspect logs for the documented PicoClaw Compose file and data directory.
PicoClaw gateway or agent was started from an interactive shell Verify the exact picoclaw gateway or agent command first, then run it through systemd, supervisor, tmux, or the documented Docker path.
A selected PicoClaw service, gateway, webhook, or supporting tool is bound to a port already used by another process
Run ss -tulpn and move one service to a different port.
A required PicoClaw service, gateway, webhook, or supporting tool port is not open Open only the required port and keep all other ports restricted.
Configuration is absent or incomplete Compare the generated configuration with the selected deployment path and add only the secrets and paths required.
Key is wrong, expired, or lacks access Rotate the key through the provider and update the server configuration.
Logs, caches, or repositories grew over time
Check df -h, rotate logs, clean caches, and scale storage if needed.
Too many gateway sessions, model calls, or background tasks Reduce concurrency, inspect process memory, review logs, and scale the VPS if the workload is valid.
When This Setup Is Not Necessary
Local testing is enough
You may not need a VPS if you are only testing PicoClaw locally, working from one private machine, reviewing a small repository, or experimenting without persistent SSH access.
Server management may be unnecessary
This setup is not ideal if you do not want to manage Linux updates, SSH access, firewall rules, disk usage, credentials, or repository permissions yourself.
Use a VPS for persistent remote state
Use a VPS when the workspace, runtime state, logs, tools, and assistant workflow should stay available in a controlled remote environment.
Ready to run PicoClaw on an always-on VPS?
Deploy a self-managed PicoClaw VPS and use this guide as your review checklist while you prepare the setup.
FAQ
Can I run PicoClaw on a VPS?
Yes for testing and self-managed deployments when the release supports your Linux distribution and runtime path. Use current official documentation, and avoid production use until upstream guidance supports it.
Do I need a GPU VPS for PicoClaw?
Not for the VPS runtime pattern described here. This PicoClaw guide focuses on the runtime, provider access, channel configuration, gateway logs, and lightweight server-side tasks; verify separate hardware needs if you plan local model inference or vision-heavy workloads.
Does Virtarix provide API keys or model access?
No. Bring your own provider accounts, credentials, API keys, model access, repositories, and framework configuration.
What VPS size should I use for PicoClaw?
Start with the recommended Virtarix S plan shown on this page for a practical test deployment, then scale after measuring CPU, RAM, storage, process count, gateway activity, and build requirements.
Can PicoClaw keep running without my local machine?
Yes, if PicoClaw is run as a server-side process using a documented service or process-management method. The VPS keeps the PicoClaw runtime, configuration, logs, gateway process, and provider credentials separate from your local desktop session.
Can I use Docker for this setup?
Use Docker when the official PicoClaw documentation supports it or your deployment design calls for it. Otherwise use the official runtime path.
Should I use PicoClaw nightly builds on a VPS?
Use stable releases for a safer VPS baseline. Use nightly or pre-release builds only when you intentionally accept instability and have a rollback snapshot.
Is Virtarix operating PicoClaw for me?
No. Virtarix provides the VPS infrastructure. You install, configure, secure, update, and operate the software you run on it.