# Remote access (/docs/agents/remote-tunnel)



By default an agent connects to SimpliGen on the same machine. If you run your agent somewhere else, like on a VPS, you can still reach SimpliGen over a secure tunnel, with no changes to the app.

<Callout type="info" title="The idea">
  SimpliGen's control service only listens on `localhost`, for safety. So the trick is to tunnel the remote machine's `localhost` to your SimpliGen machine's `localhost`. An SSH reverse tunnel does exactly that, and SSH handles all the encryption and authentication.
</Callout>

## What you need [#what-you-need]

* SimpliGen running on your home machine, with a pairing token (create one in **Settings -> Connect an agent -> Manual setup**).
* The control-API port. On Windows it is in `%APPDATA%\simpligen\agent-api.json`, for example `48199`.
* SSH access from your home machine to the remote machine.

## Open the tunnel [#open-the-tunnel]

From your **home machine** (where SimpliGen runs), open a reverse tunnel to the remote machine. Replace `48199` with your port and `user@your-vps` with your server:

```bash
ssh -N -R 48199:localhost:48199 user@your-vps
```

This makes `localhost:48199` on the remote machine forward to `localhost:48199` on your home machine. Leave it running while the agent works.

## Point the agent at it [#point-the-agent-at-it]

On the **remote machine**, configure your agent's MCP server with your token and the port:

```json
{
  "mcpServers": {
    "simpligen": {
      "command": "npx",
      "args": ["-y", "@simpligen/mcp"],
      "env": {
        "SIMPLIGEN_TOKEN": "sg-agent-...",
        "SIMPLIGEN_API_PORT": "48199"
      }
    }
  }
}
```

`SIMPLIGEN_API_PORT` tells the connector which port to use, since the remote machine has no SimpliGen install to detect it from. Each request travels down the tunnel to SimpliGen on your home machine.

<Callout type="warn" title="Keep both running">
  SimpliGen must stay open on your home machine, and the tunnel must stay up. If either stops, the agent loses its connection until you restart it.
</Callout>

## Using Tailscale or a private network [#using-tailscale-or-a-private-network]

If you use a private mesh network like Tailscale, run the same SSH reverse tunnel over it for a stable link without opening any ports on your home router. The mechanics are identical: the remote machine's `localhost` still forwards to your home machine's `localhost`.

## A note on security [#a-note-on-security]

Because the tunnel terminates at `localhost` on both ends, you are not exposing SimpliGen to the public internet. SSH encrypts and authenticates the connection, and your pairing token authorizes the agent. You can revoke that token from **Connected agents** at any time to cut off access.