Know it’s ready.
VPS
sudo agentvps status
sudo agentvps call health_check '{"browser":true}'Check the workspace identity and each capability. A running service alone doesn’t prove the browser or desktop works.
VERSION 0.0.1 EARLY RELEASE ↗Your agent.
Your agent.
Your computer.
A real Linux desktop on your own VPS.
Connect your agent. Watch the work. Take over anytime.
WORKS WITHCodexClaude CodeAny MCP client
ONE COMPUTER. SHARED WITH YOUR AGENT.See the full desktop ↗
Your agent’s computerACTUAL VPS DESKTOP
Browser, terminal & files in one workspaceWatch · Take over · Return control
01
See the work.
Stream a full Linux desktop. Move windows, change resolution, go fullscreen, or use the mouse and keyboard yourself.
02
Bring your agent.
Connect Codex, Claude Code or another MCP client. Its tools operate the same browser and files you see on screen.
03
Keep the workspace.
Downloads, code and artifacts share one filesystem. Files and the browser profile stay on your VPS between sessions.
FROM VPS TO WORKSPACEMake yourself
Make yourself
at home.
Start with an Ubuntu VPS and an SSH login.
The installer takes care of the desktop and tools.
UBUNTU 22.04 / 24.04X64 / ARM642 GB+ RAM5 GB FREE DISKSUDO ACCESS
01
Install on your VPS.
SSH into the computer you want your agent to use. Run:
VPS TERMINAL
curl -fsSL https://agentvps.ai-infra.org/install.sh -o install-agentvps.sh
sudo bash install-agentvps.shInstalls version 0.0.1: the CLI, service, Chromium, and Linux desktop. The download is checked against a pinned SHA-256. Read the installer ↗
02
Open your computer.
Allow TCP 8080 in your VPS firewall, then open http://YOUR_VPS_IP:8080. Retrieve your access token locally and paste it into the login screen:
VPS TERMINAL
sudo cat /var/lib/agentvps/tokenKeep this token private. Public IP access uses HTTP; use HTTPS or SSH forwarding for private work. Port 8081 is optional for sharing web previews.
03
Connect your agent.
On the computer running your agent, install the client with Node.js 22 or newer:
AGENT’S COMPUTER
npm install -g https://github.com/agentsdance/agentvps/releases/download/v0.0.1/agentvps-0.0.1.tgzCopy the token over SSH, then connect. Replace ubuntu with your SSH username if different:
AGENT’S COMPUTER
mkdir -p ~/.config/agentvps
umask 077
ssh ubuntu@YOUR_VPS_IP 'sudo cat /var/lib/agentvps/token' > ~/.config/agentvps/vps.token
agentvps connect --url http://YOUR_VPS_IP:8080 --token-file ~/.config/agentvps/vps.token
agentvps status
codex mcp add agentvps -- agentvps mcpThe last line registers Codex. For Claude Code or another MCP client, use command agentvps with arguments ["mcp"]. See the connection config ↓
A SMALL PROMPT. A REAL COMPUTER.
Hand this to your agent.
Give your agent your VPS hostname and SSH username. Use an existing SSH key; keep private keys and access tokens out of chat.
COPY INTO CODEX, CLAUDE CODE, OR YOUR AGENT
Install AgentVPS on my VPS: <SSH_USER>@<VPS_HOST>.
Follow https://agentvps.ai-infra.org/agent-guide.md
Use my existing SSH access. Keep credentials private.
Verify the desktop and MCP by performing a harmless operation
and showing it on the live desktop. Return the desktop URL,
connection instructions and verification results.It checks the target.
Confirms the OS, architecture, permissions and intended VPS before installing.
It proves the connection.
Calls MCP, operates native apps and checks the resulting files on the same computer.
It gives you a handoff.
Your desktop URL and connection instructions, with no credentials in the reply.
ONE ENDPOINT. 47 TOOLS.Meet your agent
Meet your agent
where it works.
The local MCP bridge forwards operations to your VPS. Direct Streamable HTTP MCP is also available at http://YOUR_VPS_IP:8080/mcp with bearer authentication.
STDIO MCP CONFIG
{
"mcpServers": {
"agentvps": {
"command": "agentvps",
"args": ["mcp"],
"env": {
"AGENTVPS_URL": "http://YOUR_VPS_IP:8080",
"AGENTVPS_TOKEN_FILE": "/absolute/path/to/token"
}
}
}
}THE EVERYDAY BITSSimple to run.
Complete CLI reference ↗Simple to run.
Simple to keep.
Keep your files.
Download the next release package, then run:
VPS
sudo agentvps upgrade ./agentvps-VERSION.tgzFiles, browser profile and configuration stay. Live commands and app windows close during the restart.
Leave on your terms.
VPS
agentvps uninstall --dry-run
sudo agentvps uninstallYour data stays by default. Add --purge only to permanently delete the workspace and credentials.
GOOD TO KNOW
A few details.
Is this already an autonomous personal agent?
Version 0.0.1 supplies the remote computer and tool layer. Bring Codex, Claude Code, or another agent to operate it. Built-in conversations and a model-driven agent loop are planned.
Can I watch everything my agent does?
Browser and native desktop actions appear live on the desktop. Background shell jobs appear in Commands, and API terminal sessions appear in Remote desk. Ask your agent to use a native terminal when you want to watch commands being typed.
What happens when I take over?
Your mouse and keyboard control the desktop. New agent browser and desktop mutations are blocked until you return control. Background jobs and actions already in progress continue.
What survives a restart?
Workspace files, notes, schedules, finished job receipts and the Chromium profile persist. Live commands, terminal sessions, app windows and preview links do not. Disconnecting the viewer alone leaves the remote apps running.
Is this isolated from the rest of my VPS?
AgentVPS runs as one unprivileged Linux user. It is a single-owner computer, not a multi-tenant sandbox. Commands have that OS user’s permissions. Authentication is required for tools and desktop access.
Something didn’t start. Where do I look?
Run sudo systemctl status agentvps and sudo journalctl -u agentvps -n 50. Check cloud firewall access to port 8080, then run the health check above. Report an issue with version and error details, without your token.