> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Private network

> Let every Cloud Run reach internal services through Tailscale or Headscale.

<Info>Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).</Info>

A company can connect one private network. Every Cloud Run joins it before its harness starts, so agents reach internal services (databases, staging APIs, package registries, admin tools) by the names people use. Owners and admins set it up once in **Settings → Network**, or an integration does with an `admin` company API key; nothing is configured per Task. Every member can see which network is connected, whether it is on, and when it was last verified.

Only overlay networks that enroll a machine unattended can join a disposable sandbox. Melso supports two: **Tailscale** and **Headscale**, the self-hosted Tailscale control server.

## Tailscale

For each Run, Melso uses an OAuth client to mint a single-use, ephemeral, pre-authorized device key for your tags. The key expires after five minutes, and the client secret never leaves the Melso API.

1. **Create a tag for Runs.** In your tailnet policy file, add a tag such as `tag:melso` and grant it exactly what agents may reach. Access control stays in the policy: a Run can reach what the tag can reach, nothing more.

   ```json theme={null}
   {
     "tagOwners": {
       "tag:melso": ["autogroup:admin"]
     },
     "grants": [
       { "src": ["tag:melso"], "dst": ["tag:agent-https-service"], "ip": ["tcp:443"] }
     ]
   }
   ```

   Apply `tag:agent-https-service` only to the specific HTTPS services agents may reach. Replace it with your own restricted destination tag. Add database ports or subnet routes only when the work requires them; a subnet router must advertise any route you allow.

2. **Create an OAuth client.** In the Tailscale admin console, generate an OAuth client with the **Auth Keys** scope set to **Write** and the tag from step 1. Copy the client ID and the client secret (`tskey-client-…`); the secret is shown once.

3. **Connect it.** In **Settings → Network**, choose **Connect**, then **Tailscale**. Paste the client ID and secret, and enter the tags, separated by commas. Saving checks the client: Melso exchanges it for an access token with the `auth_keys` scope and your tags. If Tailscale refuses, nothing is saved and Settings shows why.

## Headscale

For Headscale, each Run receives the same reusable pre-auth key you configure. Use a dedicated user or tags whose network policy allows only the services and ports agents need.

<Warning>
  Anyone holding this key can enroll devices until it expires or you revoke it in Headscale. Ephemeral devices do not make the key single-use. Choose the shortest expiry your rotation process can support, replace the saved key before that deadline, and revoke an exposed key promptly. Melso does not mint a fresh Headscale key for each Run.
</Warning>

1. **Create a user for Runs**, or use tags from your Headscale policy:

   ```bash theme={null}
   headscale users create melso
   ```

2. **Create a reusable, ephemeral pre-auth key with an expiry.** This example uses [24 hours](https://headscale.net/0.26.0/setup/install/container/); choose a shorter window if practical. Add `--tags tag:melso` if your policy uses tags.

   ```bash theme={null}
   headscale preauthkeys create --user <user> --reusable --ephemeral --expiration 24h
   ```

3. **Connect it.** In **Settings → Network**, choose **Connect**, then **Headscale**. Enter the login server as an HTTPS origin with no path, such as `https://headscale.example.com`, and paste the key.

Headscale cannot be verified without enrolling a device, so the first Run is the check. When the key expires, Runs fail to join: create a new key and paste it in **Settings → Network → Edit**.

## What a Run gets

* The Run's worker joins the network before any harness, checkout step or skill runs, and leaves it when the Run completes, fails or is cancelled.
* Each Run is its own ephemeral device named `melso-` followed by the first eight characters of the Run ID. On Tailscale it carries the configured tags; the control plane removes the device after the Run.
* Subnet routes are accepted and MagicDNS names resolve by default. Turn off **Accept subnet routes** or **Use network DNS** in Settings to change that.
* Kernel mode is used when the sandbox allows it (a TUN device and passwordless `sudo`): every program reaches the network transparently. Otherwise the worker falls back to userspace networking and points the harness at a local HTTP and SOCKS5 proxy on `127.0.0.1:1055` through `ALL_PROXY`, `HTTP_PROXY` and `HTTPS_PROXY`. Only programs that honor those variables reach the network then. The Run's brief says which mode applies.
* A Run that cannot join fails before its harness starts, with `failure_reason` `private_network_unavailable` and "This task could not join the company network." It never runs half-connected. Check the credential, its tags and the tailnet policy, and the **Last error** in Settings.

Turning the network off keeps its settings; new Runs stop joining until it is on again. Turning it off or disconnecting it does not touch Runs already connected: they keep their device until they end.

## Limits

* One network per company.
* Corporate VPNs that require interactive sign-in, MFA or device posture checks (Cisco AnyConnect, GlobalProtect, Zscaler, Fortinet) cannot enroll a sandbox. Run those tasks on a worker inside the company network instead.
* In userspace mode, programs that ignore proxy variables cannot reach the network.

## Settings API

These routes accept people and admin keys: a signed-in browser session, a personal access token (`mel_…`) sent with `X-Workspace-ID`, or a company API key created with `admin` scope (see [Credential types](/api-reference/authentication#credential-types)), which acts as a company admin here. `tasks` API keys, Run tokens and MCP credentials are rejected. Any member can read the settings; only owners, admins and admin keys can change them. No response ever contains a client secret or pre-auth key, and provider response bodies are never returned or logged.

The examples use the variables from [Authentication](/api-reference/authentication) with `MELSO_TOKEN` set to a personal access token.

## API reference

Request fields, response types and endpoint permissions are defined in the [Private Network reference](/api-reference/tags/private-network). See [Pagination](/api-reference/pagination) for list conventions, or start with the [API quickstart](/api-reference/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.