---
title: "Security and data handling"
description: "How Hoplite isolates credentials, handles your data, and keeps a human in control"
canonical_url: "https://hoplite.sh/docs/workspace/security"
markdown_url: "https://hoplite.sh/docs/workspace/security.md"
---

# Security and data handling
URL: /docs/workspace/security
LLM index: /llms.txt
Description: How Hoplite isolates credentials, handles your data, and keeps a human in control
Related: /docs/agent/tools, /docs/agent/mcp, /docs/threads/review, /docs/sandboxes/environment-variables

# Security and data handling

Agents work in isolated [sandboxes](/docs/sandboxes), and the credentials that matter never enter them. This page collects how Hoplite handles source-control credentials, secrets, your conversation data, and untrusted external content — and where a human stays in the loop.

## Source code and credentials

### GitHub credentials never enter the sandbox

The raw sandbox shell never receives a GitHub App credential, so `git` and `gh` commands the agent writes cannot inherit repository authority. First-party GitHub and pull-request [tools](/docs/agent/tools) broker fresh, repository-scoped installation tokens inside Hoplite's trusted worker for the exact fetch or publication operation. Those tokens never reach the remote URL, Git configuration, workspace filesystem, or agent-authored shell.

The same boundary holds for CI investigation: the GitHub App credential stays in the trusted worker and is never exposed to the sandbox or forwarded to GitHub's signed log-download URL. Publication paths also reject repositories with tracked submodules before pushing.

### MCP credentials

Auth headers and OAuth tokens you give an [MCP server](/docs/agent/mcp) are treated as secrets end to end:

- **Encrypted individually at rest** with AWS KMS under a customer-managed key with automatic rotation. There is no shared data key whose compromise would expose everything, and a single value is capped at 4,096 bytes of plaintext — anything larger is rejected rather than stored unencrypted.
- **Auditable decryption.** Each KMS call carries an encryption context that is cryptographically bound into the ciphertext and recorded in AWS CloudTrail; only the API and agent workers hold IAM permission to use the key.
- **Never returned to a client.** Every API response masks secret values as `********`, MCP configurations are excluded from realtime sync, and values are never written to logs.
- **Decrypted in one place only:** the worker assembling an agent run, at the moment it connects to the server.
- **Changes are role-gated.** Creating, editing, or deleting a server requires a fresh owner or admin check.

Credentials imported by the [CLI](/docs/cli) follow the same model, and the import itself is opt-in: `hoplite onboard` copies server addresses only by default, nothing in the auth-state step is preselected, and nothing is uploaded until you confirm. An imported token grants Hoplite's agents the same access it granted your local tools, so rotate it upstream if you change your mind — Hoplite cannot show you a value again after saving.

### Environment variables

Project [environment variables](/docs/sandboxes/environment-variables) are encrypted per-project secrets, injected into every command the agent runs in the sandbox.

## Your data

A [CLI handoff](/docs/cli/handoff) uploads only the user/assistant conversation of your local session; tool output and hidden reasoning stay local, and running development processes and ignored files are not transferred. The cloud workspace can only see files available from GitHub — pushing local changes requires the explicit `--autopush` opt-in.

Images the agent shows you with `display_image` are stored durably; publishing one is optional and uses an unguessable URL that expires after 7 days. Transcript export and organization-wide thread history are covered in [Manage threads](/docs/threads/manage).

## External content

`web_search` runs on a worker-owned Exa credential that is never copied to project settings, repository files, or sandboxes. Search results are untrusted external content, so the agent treats them as reference material — not instructions.

Remote MCP server URLs (`http`/`sse`) may not point at loopback, link-local, private, or internal hosts, which guards against server-side request forgery. To talk to something running inside the sandbox, use a `stdio` server instead.

## Human control

[Approvals](/docs/threads/review) are the trust gate: sensitive tool calls pause for your sign-off before executing, while reads, searches, browser actions, and status checks run without interruption. File writes (`write_file`, `edit_file`, `apply_patch`), `shell`, and disruptive sandbox operations (`kill_process`, `sandbox_restart`, `sandbox_resize_down`) all wait for you — disruptive operations can kill running processes, so they are never automatic.

The agent can propose changes to its own project configuration through `project_settings_update`, and that tool always requires approval. The full approval-gated list lives in [Tools](/docs/agent/tools).

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).