/krypton-vps-codex-app

name: krypton-vps-codex-app
description: Set up, harden, audit, or explain a Linux VPS as a Codex App SSH host for Krypton-style agent workflows. Use when the user wants to move Codex or Claude Code work from a local Mac to a VPS, connect Codex App to an SSH host, configure Ubuntu 24.04/devbox tools, clone a repo remotely, run Codex/Claude/tmux/cmux on the VPS, forward ports for localhost testing, or create repeatable founder/builder setup instructions with proof checks.

Krypton VPS Codex App

Overview

Turn a Linux VPS into the machine that does the work while the operator's Mac only displays and controls it. The target result is a working Codex App SSH project where commands, edits, builds, tests, tmux/cmux sessions, dev servers, and agent runs happen on the VPS.

Do not describe this as installing Codex App on the VPS. Codex App stays on the operator's Mac or Windows machine; the VPS needs the Codex CLI and repo toolchain so the app can start the remote Codex app server through SSH.

Use the current OpenAI Codex docs for Codex App specifics when facts may have changed. The durable setup facts this skill relies on are:

• Codex App can add projects from an SSH host.
• Codex reads concrete SSH aliases from `~/.ssh/config`.
• Remote project threads run commands and edit files on the remote host.
• The remote host provides the repo files, credentials, tools, skills, MCP

setup, browser/computer-use setup, and sandbox/approval behavior.

• The remote `codex` command must be available on the remote user's login-shell

`PATH`.

Responsibility Split

Codex can prepare commands, inspect SSH config, audit the VPS, bootstrap tools over SSH when it has access, clone the repo, run checks, and explain failures.

The operator must provide or complete these human steps:

• Buy or provision the VPS if it does not exist yet.
• Create or choose the SSH key pair used for the VPS.
• Add an SSH public key in the VPS provider UI or otherwise grant SSH access.
• Approve any edit to `~/.ssh/config`, or add the SSH alias manually.
• Choose how the VPS may access their GitHub repo.
• Decide whether local-only config files should be recreated, copied, or skipped.
• Keep private keys, provider passwords, API keys, and Codex auth files secret.
• Complete Codex App Settings > Connections and choose the remote project folder.
• Complete browser/device authentication when the flow requires user login.

First Response

Start by repeating the setup goal in plain English:

You want the VPS to be the actual development machine. Codex App on the Mac
connects to it over SSH, and the repo, tools, agent sessions, builds, tests,
and dev servers run there.

Then ask this setup-state question first:

Do you already have a VPS with SSH access, or are we starting before the VPS is
created?

If the VPS does not exist yet, give a short purchase/bootstrap checklist: Ubuntu 24.04 LTS unless the repo needs something else, enough CPU/RAM/swap for builds and agent runs, SSH-key access, a non-root daily user, no public dev ports, and GitHub as source of truth. Then ask for the VPS IP, initial username, and public-key path once the VPS is ready.

If the VPS exists, ask for only the missing inputs needed for the next step:

• SSH alias or VPS IP.
• Remote username.
• Repo URL and desired remote path.
• Whether the repo is public or private.
• Which GitHub access path they want: GitHub CLI login, SSH key on their GitHub

account, read-only deploy key, or no GitHub setup yet.

• Whether they have local-only config files such as `.env`, ignored config,

MCP files, package registry auth, or provider credentials that the VPS needs.

• Stack commands if they are not obvious from the repo.
• Whether Codex should only audit or may bootstrap missing tools over SSH.
• Whether the operator wants setup, audit, troubleshooting, or public post-ready

instructions.

If the user already gave enough, proceed without more questions.

Setup Workflow

1. Host And Security Preflight

Treat this as a development host, not production.

• Use a non-root Linux user for daily work.
• If the first login is `root`, use it only for bootstrap and move the Codex

SSH alias to a non-root user before day-to-day work.

• Use SSH keys, not passwords.
• Keep GitHub as source of truth for code.
• Keep production deploy targets separate and protected.
• Do not expose dev servers, Codex app-server, Docker sockets, databases, or

private dashboards to the public internet.

• Prefer SSH port forwarding for local browser testing.
• On headless Linux VPS hosts, do not promise Browser or Computer Use unless a

supported browser/desktop stack is explicitly installed and verified. Prefer running the server on the VPS and inspecting it through a local SSH tunnel.

• Never print, paste, or commit `~/.codex/auth.json`, API keys, deploy keys,

SSH private keys, or provider tokens.

2. Mac SSH Config

Create or provide a concrete SSH alias on the Mac that runs Codex App. Do not edit `~/.ssh/config` silently; show the snippet and ask before writing unless the user already asked Codex to make the edit.

Host krypton-vps
  HostName 203.0.113.10
  User dev
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  ServerAliveInterval 30
  ServerAliveCountMax 3

Verify from the Mac:

ssh krypton-vps

3. VPS Tooling

On the VPS, install the repo's real toolchain. For a typical Ubuntu 24.04 agent box this means:

• `git`
• `gh`
• `curl`
• `jq`
• `python3`
• `ripgrep` (`rg`)
• `build-essential`
• `tmux`
• `unzip`
• `cmux` when the workflow uses it
• `node`
• `corepack`
• `pnpm`
• Docker and Compose when the repo needs containers
• Codex CLI, installed through the current official path
• Claude Code only if the operator uses it and has its auth flow ready

Do not guess a repo's install commands. Read `README.md`, package manager files, and repo docs first.

4. Codex On The VPS

The remote shell must find `