proxima-vps-setup

Set up, repair, or document a Proxima deployment on a remote Ubuntu VPS with a non-root Electron runtime, virtual desktop GUI, loopback-only VNC/noVNC/REST exposure, and SSH-stdio MCP access for local IDEs like Antigravity, Windsurf, Zed, or Claude Desktop. Use when a user asks to install Proxima on a VPS, expose the GUI safely, make REST reachable through SSH tunnels, configure `proxima-mcp`, or troubleshoot remote MCP/GUI connectivity.

Proxima VPS Setup

Use this skill to stand up or repair a Proxima-on-VPS deployment end to end.

Core rules

Run Proxima as a dedicated non-root Linux user, normally proxima.
Bind GUI, VNC, noVNC, REST, and internal IPC to loopback unless the user explicitly asks for a different exposure model.
Prefer SSH tunnels and SSH stdio transport over public TCP listeners.
Do not treat curl http://localhost:3210/... on the user's laptop as valid unless an SSH tunnel exists.
Do not open VNC, noVNC, REST, or MCP directly to the public internet by default.
Verify every layer after changing it: service status, listening ports, local curl, then remote tunnel behavior.
Warn clearly that Proxima carries meaningful operational risk and should not be recommended on a primary personal machine.

Workflow

Confirm the host assumptions and whether Proxima is already installed.
Read references/security-and-architecture.md before making user-facing safety claims.
Read references/server-setup-runbook.md and apply the server-side setup or repair steps.
Read references/local-access-and-mcp.md when configuring SSH tunnels or local IDE MCP clients.
Read references/troubleshooting.md if REST, GUI, VNC, or MCP does not work as expected.
Validate the final state with real checks, not assumptions.

Output expectations

When reporting status, keep it compact and include:

whether proxima-app.service is active
whether 127.0.0.1:3210, 127.0.0.1:5902, 127.0.0.1:6081, and 127.0.0.1:19222 are listening when expected
whether local VPS curl http://127.0.0.1:3210/v1/models works
whether ssh -T <alias> proxima-mcp works from the user side
what still blocks completion, if anything

References

Read references/security-and-architecture.md first for risk framing, binding model, and model-routing caveats.
Read references/server-setup-runbook.md for package install, systemd services, config files, wrapper creation, and validation.
Read references/local-access-and-mcp.md for SSH config, tunnels, and IDE MCP config snippets.
Read references/troubleshooting.md for the common failure modes and exact fixes.