# Security

## Check The Controls That Affect Agent Actions

Open **Approvals** to review pending actions. Open **Settings → Permissions** to change the default approval policy or Safe Mode.

![Approval detail with the requested action and review controls](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/landing/v7/2026-08-11-r1/ui/control-detail-1280.webp)

## Overview

Neotask is designed with a security-first architecture. The Gateway binds to localhost by default, all sensitive data is encrypted at rest, and agent execution can be sandboxed in isolated containers.

## Network Security

### Loopback by Default

The Gateway only listens on `127.0.0.1` (localhost) unless you explicitly change the binding mode. No external network exposure by default.

### Authentication

All WebSocket connections require authentication:

- **Token auth**, Bearer token (UUID or custom string)
- **Password auth**, Bcrypt-hashed password
- **Trusted proxy**, Pre-authenticated headers from reverse proxies
- **Local trust**, Loopback connections are implicitly trusted

### Remote Access Security

For remote access, the recommended approach is **Tailscale VPN** or **SSH tunneling**, never expose the Gateway directly to the internet.

## Device Pairing

### How Pairing Works

Every client that connects to the Gateway must be paired:

1. Device presents its identity (fingerprint + public key)
2. Gateway issues a pairing challenge (nonce)
3. Device signs the nonce with its private key
4. You approve the device through the UI
5. Gateway issues a device token for future connections

### Trust Model

- **Local devices** (loopback) are auto-approved for convenience
- **Non-local devices** require explicit approval
- Device tokens are stored locally and reused on reconnect
- Devices can be revoked at any time

## Encryption

### Data at Rest

- **AES-256-GCM**, All tokens, secrets, and API keys are encrypted at rest
- **Machine-derived keys**, Encryption keys derived via scrypt from device identity
- **No plaintext storage**, Tokens are never stored in plaintext

### Data in Transit

- **TLS**, HTTPS for API communication
- **WSS**, WebSocket Secure for Gateway connections (when using Tailscale Serve or reverse proxy)
- **HMAC signing**, Request integrity with nonce and timestamp

## Sandboxing

### Docker-Based Isolation

Agent command execution can be sandboxed in Docker containers:

- **Per-agent profiles**, Each agent can have its own sandbox configuration
- **Resource limits**, Configurable CPU, memory, and timeout limits
- **Network isolation**, Containers can be network-isolated
- **Filesystem confinement**, Agents only access their workspace
- **Custom images**, Use pre-built images with specific tools installed

### Sandbox Scopes

| Scope | Description |
|-------|-------------|
| **Per-session** | Fresh container for each session |
| **Per-agent** | Persistent container per agent |
| **Shared** | Shared container across agents |

### Workspace Access

Sandboxed agents can access their workspace directory (mounted into the container) but cannot access the host filesystem outside their workspace.

## Exec Approvals

Guardrail settings define which classes of agent actions pause for review. Check them before changing the policy for an individual request.

![Agent guardrails and approval controls](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/landing/v7/2026-08-11-r1/ui/control-guardrails-1280.webp)

Control what commands agents can execute on nodes and the Gateway host:

### Modes

| Mode | Description |
|------|-------------|
| **Allowlist** | Only pre-approved commands execute |
| **Ask** | Unknown commands prompt for user approval |
| **Full** | No restrictions (use with caution) |

### Per-Node Configuration

Each node (macOS, headless host) has its own exec approval configuration, stored locally. You can allow specific binaries (e.g., `/usr/bin/docker`, `/usr/local/bin/terraform`) while blocking everything else.

## Elevated Mode

Some operations require running on the Gateway host directly (not in a sandbox). Elevated mode is:

- Gated by explicit permission in agent config
- Only available on the Gateway host
- Disabled by default
- Auditable through logging

## Security Audit

The built-in security audit checks:

- Configuration file permissions (should be 600)
- Session file permissions
- Node.js version (security patches)
- Plaintext secret detection
- Plugin allowlist validation
- Open network interface audit
- Auth configuration completeness

The audit can automatically fix many issues when given permission.

## Best Practices

1. **Keep the Gateway on loopback**, Use Tailscale or SSH for remote access
2. **Enable sandboxing**, Run agent commands in Docker containers
3. **Use exec allowlists**, Restrict what commands agents can run on nodes
4. **Set auth tokens**, Always configure token auth, even for loopback
5. **Review agent permissions**, Use minimal tool profiles where possible
6. **Keep Neotask updated**, Updates include security patches
7. **Audit regularly**, Run security audits to catch misconfigurations
8. **Restrict plugin loading**, Only install trusted plugins