> ## Documentation Index > Fetch the complete documentation index at: https://docs.neo.projectdiscovery.io/llms.txt > Use this file to discover all available pages before exploring further. # Install a self-hosted sandbox > Install, secure, and manage a sandbox on infrastructure you control Sandbox availability depends on your plan. Accounts with cloud sandbox access receive one [Neo-managed cloud sandbox](/concepts/sandboxes) automatically and can also add self-hosted sandboxes. Self-hosted-only accounts must connect a sandbox before running tasks. The **Bring Your Own Sandbox (BYOS)** feature lets you add one or more self-hosted sandboxes when a task needs your host's files, tools, credentials, or network position. On accounts with both options, installing one does not replace the Neo-managed sandbox and cloud execution remains the default. ## Before you install Choose a machine that: * Runs macOS, Linux, or Windows on a supported CPU architecture. * Can make outbound HTTPS and secure WebSocket connections on `443/tcp`. * Has access to the files, tools, and networks that approved Neo tasks require. * Uses a dedicated, least-privileged operating system account when installed on shared or production infrastructure. * Has Docker available if you want the default Docker confinement and Neo-managed tool image. No inbound firewall ports are required. The sandbox opens an outbound tunnel to Neo and reconnects through a user-scoped system service. The sandbox service can read workspace files and run commands with the permissions of its operating system user. Install it only on a host and account approved for Neo workloads. ## Install and connect In Neo, open **Settings > Sandbox**. If your plan includes a Neo-managed sandbox, it appears under **Neo-managed**. Select **Install sandbox**, then choose **macOS / Linux** or **Windows**. Neo generates a command containing your API key and, when required, your Neo API URL. Sandbox settings showing the operating system selector and generated self-hosted sandbox install command Copy and run the command on the machine you want Neo to use. The installer downloads the verified `neo-sandbox` binary, registers the host, and configures its background service. Treat the copied command as a secret because it contains your Neo API key. Do not store it in tickets, shell scripts, or shared logs. Wait for the host to appear under **Self-hosted** with a **Running** status. On the host, you can run: ```bash theme={"system"} neo-sandbox check neo-sandbox service status ``` `neo-sandbox check` should finish with `Result: READY`. Sandbox settings showing a Neo-managed sandbox and a self-hosted macbook-pro sandbox with Running status Start a task, terminal, or files session and select the self-hosted sandbox when you need its network position, files, or tools. If your account also includes a Neo-managed sandbox, leave the selector on it for normal cloud execution. Neo task composer with the sandbox selector open and a self-hosted macbook-pro sandbox selected For normal deployments, install one sandbox service per host under the intended operating system account. Re-running the install command under the same account updates or reconnects the existing sandbox instead of creating another one. To add another host, return to **Settings > Sandbox** and select **Install sandbox** again. ## Network requirements Allow outbound `443/tcp` from the host. No inbound connection from Neo is required. | Destination | Purpose | | -------------------------------- | ------------------------------------------------------- | | `neo.api.projectdiscovery.io` | Registration, heartbeat, and token refresh over HTTPS | | `tunnel.neo.projectdiscovery.io` | Persistent outbound tunnel over secure WebSockets | | `get.projectdiscovery.io` | Installer, update manifests, and binaries | | `ghcr.io` | Docker tool image pulls when Docker confinement is used | If your Neo environment uses custom API or tunnel endpoints, allow the hostnames provided by your administrator instead. ### Proxies and restricted networks The sandbox host needs approved routes to the Neo API, tunnel, and installation or update endpoints. The sandbox's HTTP CONNECT proxy setting applies only to the persistent tunnel. It does not proxy API registration, token refresh, installer downloads, or update traffic. If the host cannot reach the tunnel directly, configure an approved CONNECT proxy or relay. The host must still reach the Neo API and installation or update endpoints through routes approved by your organization. Verify all required routes with `neo-sandbox check`. Network controls for the daemon are separate from the command network policy described below. The daemon must retain access to Neo even when confined commands have no egress. ## Confine mode Confine mode controls `/exec` command children on a self-hosted sandbox. The daemon, tunnel, file APIs, file index, watcher, and computer-use integrations continue to run on the host. When `NEO_CONFINE` is unset: * A sandbox installed on a bare host defaults to **Docker** confinement. * A sandbox already running inside a container defaults to **off** because the outer container is the boundary. | Value | Command execution | Filesystem behavior | Tool source | | -------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | --------------------------- | | `docker` | Runs through `docker exec` in a managed, long-lived tool container | Workspace is bind-mounted; host file APIs remain outside the container | Neo tool image | | `auto` | Uses Seatbelt on macOS or bubblewrap on Linux | Writes are limited to the workspace and temporary directory; host reads remain available | Tools installed on the host | | `off` | Runs directly on the host | Uses the permissions of the sandbox service user | Tools installed on the host | Windows does not currently provide a native confiner for `auto`. Use Docker confinement when Windows commands require an enforceable container boundary. On Linux, native mode requires `bwrap` on the service user's `PATH`. macOS provides Seatbelt through `sandbox-exec`. If the requested confiner is unavailable, the service reports a warning and can fall back to another available rung or unconfined execution. Always verify the active runtime with `neo-sandbox check`. ### Choose a confine mode * Keep the default `docker` mode when you want a consistent security toolchain and container boundary. * Use `auto` when the required tools are already installed on macOS or Linux and commands should use native OS confinement. * Use `off` only when commands must run directly on the host and your host policy accepts that trust boundary. The background service stores its confine settings when the operating system service is installed. To change the mode on an existing sandbox, stop and reinstall the service unit. This keeps its registration, configuration, and workspaces: ```bash macOS and Linux theme={"system"} neo-sandbox service stop neo-sandbox service uninstall NEO_CONFINE=auto neo-sandbox service start ``` ```powershell Windows theme={"system"} neo-sandbox service stop neo-sandbox service uninstall $env:NEO_CONFINE = "docker" neo-sandbox service start ``` Run `neo-sandbox check` after changing the mode. Review the reported runtime and warnings to confirm the expected confiner is active. ## Command network policy Confined commands can access the network by default. This supports scanning, package installation, and calls to target services. Set the following value to deny all egress for confined `/exec` commands: ```bash theme={"system"} NEO_CONFINE_NETWORK=deny ``` `off` and `none` preserve the default allowed behavior. `deny` is an all-or-nothing policy. Confined commands cannot scan targets, download packages, resolve external dependencies, or call internal services while it is active. Network denial is enforced only by an active confiner: | Confine mode | Network denied? | Enforcement | | ----------------- | --------------- | -------------------------------------------------- | | `docker` | Enforced | Docker starts the tool container without a network | | `auto` on macOS | Enforced | Seatbelt denies network access | | `auto` on Linux | Enforced | bubblewrap uses an isolated network namespace | | `auto` on Windows | Not enforced | No native Windows confiner is currently available | | `off` | Not enforced | Commands run with the host's network access | The policy applies to command children, not to the sandbox daemon's API and tunnel traffic. A command explicitly routed to the host also bypasses the policy. Configure confinement and network policy together: ```bash macOS and Linux theme={"system"} neo-sandbox service stop neo-sandbox service uninstall NEO_CONFINE=docker \ NEO_CONFINE_NETWORK=deny \ neo-sandbox service start ``` ```powershell Windows theme={"system"} neo-sandbox service stop neo-sandbox service uninstall $env:NEO_CONFINE = "docker" $env:NEO_CONFINE_NETWORK = "deny" neo-sandbox service start ``` ## Data and security boundaries * Workspace files, the file index, and service configuration remain on the host. * Neo can request file operations and command execution through the encrypted outbound tunnel. * File content read by an agent and command output returned to a task can be transmitted to Neo. * Docker confinement applies only to command children. It does not containerize the tunnel, file APIs, or computer-use integrations. * Host-mode and computer-use workflows can require broader host access than confined command execution. * Network denial for commands does not replace host firewall, endpoint security, identity, or data-loss-prevention controls. On macOS, access to protected folders or resources can trigger system permission prompts. Approve only the resources needed for the current workflow. You can review previous decisions in **System Settings > Privacy & Security**. ## Update the sandbox **Automatic updates are enabled by default.** The background service checks for verified updates, stages them, and applies them when the sandbox is idle. No manual action is normally required. You can still check for or apply an update manually: ```bash theme={"system"} neo-sandbox update --action check neo-sandbox update --action apply ``` Use `--target binary` or `--target docker` to update only the executable or Docker tool image. Registration, credentials, configuration, and workspaces remain in place during an update. To opt out of automatic updates, set `NEO_UPDATE_DISABLE` when configuring the service: ```bash macOS and Linux theme={"system"} NEO_UPDATE_DISABLE=1 neo-sandbox service start ``` ```powershell Windows theme={"system"} $env:NEO_UPDATE_DISABLE = "1" neo-sandbox service start ``` When automatic updates are disabled, your organization is responsible for checking and applying security and compatibility updates. ## Connect, disconnect, and remove | Action | Result | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Disconnect** in Neo | Pauses Neo access while keeping the service registration, configuration, and workspaces. Select **Connect** to resume. | | `neo-sandbox service stop` | Stops the tunnel locally while preserving registration and files. | | **Remove** in Neo | Unlinks the sandbox from your account. Re-run the install command or start the service with a new API key to register it again. | | `neo-sandbox service uninstall` | Removes the operating system service but keeps local configuration and workspaces. | | `neo-sandbox service purge --yes` | Removes the service configuration and workspaces. Add `--remove-binary` to remove the executable. | Use **Disconnect** for a temporary pause. Use **Remove** when the account should no longer trust that installation. ## Troubleshooting Always start with: ```bash theme={"system"} neo-sandbox check neo-sandbox service status ``` Confirm the install command included a valid API key, DNS works, and outbound `443/tcp` is allowed to the Neo API and tunnel. Then run `neo-sandbox service start` followed by `neo-sandbox check`. Start or restart the local service: ```bash theme={"system"} neo-sandbox service stop neo-sandbox service start neo-sandbox check ``` Confirm that **Settings > Sandbox** shows the sandbox as **Running**. Verify DNS and outbound access to `tunnel.neo.projectdiscovery.io:443`. For a corporate proxy or restricted network, configure an approved CONNECT proxy or relay and run `neo-sandbox check` again. Confirm the Docker CLI and daemon are available to the sandbox service user with `docker info`. Check that the host can pull the Neo tool image from `ghcr.io`. Review `neo-sandbox check` for fallback or unconfined-runtime warnings. Check whether `NEO_CONFINE_NETWORK=deny` is configured. This setting intentionally blocks all network access for confined commands. Remove it or set it to `off` only when the task is approved to access the network. Avoid running the sandbox with `sudo` after installing it as a normal user. Verify that the service account owns the sandbox configuration and workspace directories. This is expected when commands or computer-use workflows access protected resources. Grant only the minimum access required for the approved task. ## Related configuration * [VPN](/platform/settings/vpn) extends the Neo-managed cloud sandbox into a private network. * [Egress IP](/platform/settings/egress-ip) documents source IP behavior for cloud and self-hosted sandboxes. * [SSH connections](/concepts/ssh-connections) provide targeted access to a separate remote host. * [Pre-installed tools](/platform/tools/pre-installed-tools) explains how tool availability differs between cloud and self-hosted execution.