First VPS check with Claude Code or Codex on Mac

Apple Silicon · macOS 14.2+ · Direct-download build with Agent Bridge

By Nexus Shell · Published September 12, 2026

Connect your coding agent to a saved test server, open a visible terminal, and check uptime and root-disk usage. This walkthrough uses Nexus Shell Agent Bridge and gives you a task to copy, expected results, and help with setup failures. Configure authentication in the app without pasting a password or private key into chat.

Still deciding whether to use the integration? Read the Agent Bridge features, tools and access controls. This page starts with setup and ends when two checks return results. It is maintained by Nexus Shell's developer.

Before you start

• Use an Apple Silicon Mac running macOS 14.2 or later, with the official direct-download or Homebrew build of Nexus Shell. TestFlight and Mac App Store builds do not include Agent Bridge.
• Have Claude Code or Codex installed and a test VPS account you are authorized to use. Prefer a limited account; this task needs no sudo.
• Have the server host-key fingerprint available from a trusted source so you can verify the connection in the app.
• Keep passwords, private keys and passphrases in your local credential workflow. Model providers and third-party gateways can receive chat and tool output; review output before sharing it.

1. Verify the saved connection yourself

Create a connection in Nexus Shell. Enter the password or select your key in the app, then connect manually and verify the server's host key. Confirm that you reached the intended test server. Leave credentials out of the connection name, tags and notes, because the agent can receive those fields.

If this manual connection fails, resolve it before configuring the agent. Agent Bridge uses the saved connection; it does not repair an incorrect username, key or host address.

2. Connect your coding agent

Enable Settings → Agent Bridge. Copy the setup instruction displayed there into Claude Code or Codex. It configures the MCP integration; it is not your SSH password. Use the instruction from your installed app rather than an old socket configuration copied from a blog.

When the agent first calls a tool, review the authorization dialog in Nexus Shell and approve the intended agent. If the tools are not available, check the integration status in the coding client before continuing.

3. Run the first check

After configuring a test connection, copy this task into your agent. It contains no server address, account name, password or private key. It deliberately asks the agent to confirm the target before running commands.

Use Nexus Shell Agent Bridge for this task.
List saved connections, then ask me to choose the test server.
Do not create or update a connection or request a password or private key.
After I confirm the server, open a visible terminal for that connection.
Run only uptime and df -h /, then summarize uptime and root-disk usage.
Do not use sudo, install anything, restart services, read files, or change settings.
Do not fall back to local shell SSH or read local SSH/keychain files.
If authentication or permissions fail, stop and explain what I need to check in the app.

These instructions limit the requested task; they do not enforce a read-only account or sandbox. Commands retain the SSH account's permissions. For the full limits, read Agent Bridge access controls.

4. Verify the result before asking for more

• The agent asks you to choose a saved connection. If the choice is ambiguous, identify it yourself rather than letting the agent guess.
• A visible terminal opens for that connection. If you only receive a text summary and no tab, stop and check whether the agent used headless execution or another tool instead.
• The terminal shows uptime and df -h / results. Uptime reports how long the server has been running and its load averages; the disk command reports capacity and usage for the filesystem containing the root directory.
• The summary agrees with the visible output. A successful check requires both commands to complete; an authentication error or an empty result is not success.

This task does not diagnose an outage or authorize a repair. If disk usage is high, choose a separate inspection task before deleting files. Load averages alone do not identify a faulty process.

If a step fails

Agent Bridge is missing from Settings

Check the distribution first. Use the official direct-download or Homebrew build on a supported Mac. The TestFlight and Mac App Store builds exclude the bridge; paying for Pro does not add it to those builds.

My agent asks me to paste the SSH password

Stop that step and configure or repair the saved connection in Nexus Shell. Then retry the connection through the app. Ask the agent to use the existing connection ID, not create a new password connection.

The connection works in the app but the agent cannot use it

Check that Agent Bridge is enabled, that the MCP integration is available in your client, and that you approved the correct agent in Nexus Shell. Reuse the current instruction from Settings rather than copying an old socket configuration from a blog.

A command fails or the disk output is unexpected

Check the command's actual terminal output and confirm the selected host. Keep the task stopped if the account cannot run a check. The disk command describes the filesystem mounted at the root path, not every attached disk or container volume. Neither command requires sudo.

Already use an SSH alias? Run the same check from Terminal

Agent Bridge is optional. If you already have a working SSH host alias with a verified host key, you can run the same two commands through your existing OpenSSH setup:

ssh staging-check 'uptime; df -h /'

Replace staging-check with your configured alias locally. If you let a coding agent invoke it, review that client's shell and file permissions separately: using an alias avoids pasting a private key into chat but does not restrict access to local key files.

Choose the next task

Agent Bridge has no separate Pro gate. Connection management and basic terminal commands are available with the Free tier for personal, non-commercial use. SFTP, monitoring and other Pro capabilities retain their feature requirements. Registration starts the existing seven-day Pro trial; current pricing and terms explain commercial use and the lifetime purchase. Your model provider's charges are separate.

Once the first check works, inspect a specific issue with a bounded request. For container problems, use the remote Docker troubleshooting guide. For configuration editing, read the remote file editing workflow before allowing any write. For other available actions, consult the Agent Bridge tool list.

Sources and verification scope

This is a setup guide based on the shipped feature documentation and a review of the connection-tool implementation. It is not a claim of an independent security audit, a newly recorded VPS session or universal compatibility with every MCP client.

• OpenSSH client configuration: host aliases, identity selection, forwarding and host-key checking.
• OpenSSH authentication agent: local agent behavior and its access limits.
• Claude Code security: client permissions and MCP trust.
• Nexus Shell Agent Bridge: availability, setup and tool boundaries.