99.9% Uptime SLA
Deutsch
|
$USD €EUR
| LOGIN
Virtarix Logo
Pricing Company
Log in Sign up Today

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: NVMe storage, full root access, global locations, and an always-on server environment. You bring your own PicoClaw setup, provider access, API keys, repositories, tools, and configuration.

Deploy a PicoClaw VPS
Trustpilot rating: 4.5 out of 5

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.

01

Users testing lightweight agent runtimes

Use a VPS when a small always-on environment is enough but uptime, SSH access, and logs still matter.

02

Builders who prefer a small server footprint

Keep dependencies, environment files, repositories, and process supervision lean while preserving a remote runtime.

03

Operators who want logs and state on a server

Move runtime output, configuration, credentials, and restart notes into a dedicated server context.

04

Technical users comfortable reviewing early-stage framework notes

Virtarix supplies self-managed VPS infrastructure; you validate PicoClaw instructions, production suitability, updates, and security controls yourself.

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.

A Linux VPS, such as Ubuntu or Debian, supported by the PicoClaw release or PicoClaw deployment path you choose.

SSH access to the server.

Root or sudo access.

Basic terminal knowledge.

Git and the package managers required by PicoClaw.

Docker and Docker Compose only if you choose the documented PicoClaw Docker path for the launcher or gateway.

Go and the Web UI toolchain, such as Node.js or pnpm, only when the selected PicoClaw source or launcher path requires them.

Your own API keys, provider accounts, model access, repositories, and configuration.

A domain name, reverse proxy, SSH tunnel, and firewall rules only if you intentionally expose a web interface, gateway, or webhook endpoint beyond localhost.

Backups or snapshots before production use or major upgrades.

If you are still choosing infrastructure, compare the matching PicoClaw VPS hosting page before choosing a plan.

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 and flags.

Precompiled binary

Best when you want the simplest lightweight VPS install path for a supported Linux architecture.

Source build

Best when you need to patch, audit, or build PicoClaw with Go and the Web UI toolchain.

Docker Compose gateway

Best when you want config, data, and restart behavior under a containerized setup.

Launcher WebUI

Best for first-time configuration before editing config files directly.

Choose the simplest path that matches your operating model; avoid mixing installer, source, and container paths until the first deployment is understood.

Recommended VPS Requirements

Minimum starting point for a test environment:

Minimum starting point for a test environment

Use this to validate the workflow before committing to an always-on deployment.

  • 2 CPU cores
  • 4 GB RAM
  • 30 GB NVMe storage
  • Ubuntu VPS or another supported Linux server
  • Root access

Recommended Virtarix starting point

Cloud VPS S

$5.50/month

Recommended Virtarix starting point:

  • Cloud VPS S at $5.50/month
  • 3 CPU cores
  • 6 GB RAM
  • 50 GB NVMe storage
  • Unlimited bandwidth
  • 1 snapshot
  • 1 Backup slot
  • IPv4 + IPv6

The recommended starting point gives PicoClaw CPU headroom for background tasks and package builds, RAM for dependencies and runtime processes, NVMe storage for lightweight binaries, small config files, gateway experiments, and release-change testing, and root access for packages, services, and firewall configuration.

Recommended Architecture

The VPS is the runtime layer. You connect over SSH, configure PicoClaw, keep logs and runtime state on the server, and control API or model provider access yourself. For sizing context, return to PicoClaw VPS hosting before moving from test to production use.

User

Operator or developer controlling the workflow.

SSH

Secure access into the server.

Virtarix VPS

Runtime, storage, network, and package layer.

PicoClaw runtime

PicoClaw runtime layer for the workflow.

API/model provider

External model access and provider credentials.

Repositories, tools, and integrations

Workspace files and other automation integrations.

Step-by-Step Setup Flow

Follow this sequence as a practical deployment checklist, but confirm PicoClaw-specific versions, installer flags, and service commands against current official documentation before production use.

Deploy and connect

Prepare the VPS, connect over SSH, and create a clean workspace before installing PicoClaw-specific dependencies.

Deploy the VPS

Choose Ubuntu or another Linux distribution supported by PicoClaw. 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 over SSH

ssh root@YOUR_SERVER_IP

Update the server

sudo apt update && sudo apt upgrade -y

Create a non-root user where practical

Log back in as the non-root user before continuing if your security policy requires it.

adduser deployusermod -aG sudo deploy

Prepare a private runtime workspace

Create 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/config"printf '%s\n' "# add real provider keys privately" > "$APP_HOME/config/env.example"chmod 600 "$APP_HOME/config/env.example"

Install and configure

Install base packages, follow the current upstream install path, and configure runtime/environment settings.

Install base dependencies

sudo apt install -y git curl wget unzip ca-certificates gnupg

Install runtime dependencies

The official PicoClaw repository describes PicoClaw as a Go-based project. For source or 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.

Install or clone PicoClaw

PicoClaw upstream docs recommend downloading from picoclaw.io or GitHub Releases for precompiled binaries, and document Go/Node/pnpm requirements for source builds. Match the release asset to the VPS CPU architecture before downloading or running it; the command below is an x86_64 Linux example, not a universal binary path.

# x86_64 Linux example only; choose the matching release asset for your VPS architecturewget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_x86_64.tar.gztar -xzf picoclaw_Linux_x86_64.tar.gzchmod +x ./picoclaw./picoclaw onboard# Source build path for development or auditinggit clone https://github.com/sipeed/picoclaw.gitcd picoclawmake depsmake build

Configure PicoClaw settings

For PicoClaw, 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, not in a generic repository .env file unless your selected path explicitly documents that.

# If you installed the binary locally, use ./picoclaw instead of picoclawpicoclaw onboardnano ~/.picoclaw/config.jsonpicoclaw status

Start PicoClaw

Start with the command path you verified during onboarding. For a simple CLI test, run a one-shot message or interactive session. For a messaging gateway, keep access local while testing; only bind or proxy it for remote access after reviewing the current host/public-access setting, channel authentication, and firewall rules.

# If you installed the binary locally, use ./picoclaw instead of picoclawpicoclaw agent -m "test runtime"picoclaw agentpicoclaw gateway

Run, secure, and maintain

Keep the selected PicoClaw runtime observable, lock down access, test the setup, and plan ongoing maintenance.

Keep It Running

Use the process-management path that matches the deployment you selected. For a binary or source install, verify the exact PicoClaw command first, then place only that command behind systemd, supervisor, tmux, or another controlled process manager. For the documented Docker path, use the PicoClaw Docker Compose file and generated data directory, and keep Docker lifecycle commands separate from the binary examples.

# Binary or source pathpicoclaw statuspicoclaw gateway# Docker path: run the Compose file documented by the current PicoClaw release# and keep its generated docker/data/config.json and workspace data backed up.

Secure the VPS

Use SSH keys where possible, restrict password login if appropriate, enable a firewall, expose only the ports PicoClaw actually needs, protect PicoClaw config/security files and channel credentials, keep packages updated, and use backups or snapshots before major changes.

Test the Setup

Confirm the PicoClaw process starts, check logs, test provider authentication, test any webhook or interface the setup uses, restart the VPS, and confirm the service returns cleanly.

Maintain It Over Time

Review PicoClaw logs, rotate keys when needed, monitor disk usage, monitor RAM and CPU usage, update framework dependencies, snapshot before upgrades, and keep rollback notes.

Why PicoClaw Benefits from a VPS

PicoClaw is positioned as lightweight, but a small footprint still benefits from server uptime, SSH access, logs, environment files, and a controlled place to run background work.

01

Lightweight always-on runtime

Keep PicoClaw available on a small server without tying background work to a local desktop session.

02

Minimal dependency surface

Use a narrow VPS setup with only the packages, ports, repositories, and credentials the experiment actually needs.

03

Server-side logs and rollback notes

Keep process output, failed starts, update notes, environment files, and rollback steps in one place.

04

Early-stage caution

Keep the first server narrow: one user, one small set of integrations, a firewall, limited ports, and clear logs. The official repository warns that the project is in rapid development, so keep production-suitability language aligned with the official documentation before production use.

PicoClaw use-case article

Read the PicoClaw article for feature context, practical workloads, and VPS-hosting fit before you choose the setup path.

PicoClaw use-case article

Security Basics for PicoClaw on a VPS

Treat the PicoClaw server as a privileged runtime. Security should be part of the setup, not a later cleanup task.

Use SSH keys where possible.

Keep root login limited.

Use a non-root user where practical.

Restrict ports.

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.

Warning

Privileged runtime

The server can contain lightweight binaries, config files, gateway experiments, credentials, logs, and release-change notes. Harden it before production use.

Troubleshooting

Common setup problems to check before blaming the VPS or framework.

SSH issues

SSH connection refused

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.

Permission denied over SSH

Wrong key, wrong user, or disabled login method Check ~/.ssh/authorized_keys, user permissions, and your SSH config.

Dependency and runtime issues

Missing dependencies

Base packages or runtime packages were not installed Re-run the dependency step and compare runtime versions with official PicoClaw docs.

Go, Node.js, or pnpm mismatch

The selected PicoClaw build path expects a different runtime version Use the version manager or package source recommended by upstream docs.

Docker and process issues

Docker service not running

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.

Process stops after logout

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.

Port and firewall issues

PicoClaw service, gateway, webhook, or supporting tool port already in use

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.

Firewall blocking picoclaw service, gateway, webhook, or supporting tool access

A required picoclaw service, gateway, webhook, or supporting tool port is not open Open only the required port and keep all other ports restricted.

Environment and API key issues

Missing configuration or credentials

Configuration is absent or incomplete Compare the generated configuration with the selected deployment path and add only the secrets and paths required.

Invalid API key or provider error

Key is wrong, expired, or lacks access Rotate the key through the provider and update the server configuration.

Disk and memory issues

Disk space issues

Logs, caches, or repositories grew over time Check df -h, rotate logs, clean caches, and scale storage if needed.

High memory usage

Too many gateway sessions, model calls, or background tasks Reduce concurrency, inspect process memory, and scale the VPS if the workload is valid.

Ready to run PicoClaw on an always-on VPS?

Deploy a PicoClaw VPS and use this guide as your review checklist while you prepare the setup.

Deploy a PicoClaw VPS

FAQ

Can I run PicoClaw on a VPS?
Yes, if the PicoClaw release supports the Linux distribution and runtime path you choose. Use this guide together with the current official documentation.

Do I need a GPU VPS for PicoClaw?
Not for the VPS runtime pattern described here. This PicoClaw guide focuses on the PicoClaw runtime, provider access, channel configuration, gateway logs, and lightweight server-side tasks; verify separate hardware needs if you plan local model inference.

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 PicoClaw with the recommended Virtarix Cloud VPS S for a practical first deployment, then scale after measuring CPU, RAM, storage, and process count for lightweight binaries, small config files, gateway experiments, and release-change testing.

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.

Is Virtarix operating PicoClaw for me?
No. Virtarix supplies self-managed VPS infrastructure. You install, configure, update, monitor, and secure PicoClaw yourself.