How to Give AI Agents Permissions Without Giving Them Your Entire Computer
Learn to grant AI agents least-privilege access using sandboxes, scoped tokens, and audit logs. Step-by-step configs included.
The Problem: Your Agent Has Root and That's Terrifying
You've built an AI agent that can browse the web, run shell commands, and edit files. It's powerful. Then you realize it runs with your user account's full permissions. One bad prompt, one prompt injection, and it can delete your home directory, exfiltrate your SSH keys, or overwrite your dotfiles.
The fix is not to avoid agents. The fix is to give them the minimum permissions they need, scoped to a specific task, with audit trails. This article walks through a practical setup: a containerized sandbox, a scoped API token, and an audit log. You'll have a runnable example by the end.
- Understand the risk: agents inherit your permissions unless you limit them.
- Learn the three pillars: sandboxing, scoped credentials, and observability.
- Apply a copy-paste Docker setup to isolate your agent.
- Create a least-privilege API token for your agent's external calls.
- Set up audit logging to see exactly what the agent did.
Before You Start: What You'll Need
You need Docker installed, a recent version of Node.js (18+), and a terminal. We'll use a simple TypeScript agent loop that calls an LLM and can execute a couple of safe tools. The example uses OpenAI's API, but the pattern applies to any provider.
- Docker 20.10+ with docker compose plugin.
- Node.js 18+ and npm.
- An OpenAI API key (or any LLM API key) for the agent's brain.
- Basic familiarity with shell commands and JSON.
Step 1: Run Your Agent in a Docker Sandbox
The first line of defense is to run the agent inside a container with no access to your host filesystem, network, or processes. We'll use a minimal Node.js image and mount only a dedicated working directory.
Create a project folder and a Dockerfile. The Dockerfile installs Node, sets a non-root user, and copies the agent code. We'll also create a docker-compose.yml to define the sandbox with resource limits and a read-only root filesystem.
FROM node:18-alpine
RUN addgroup -S agent && adduser -S agent -G agent
WORKDIR /app
COPY package*.json ./
RUN npm install --only=production
COPY . .
USER agent
CMD ["node", "dist/index.js"]services:
agent:
build: .
container_name: my-agent
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
volumes:
- ./workspace:/workspace
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- AGENT_WORKSPACE=/workspace
mem_limit: 512m
pids_limit: 100
restart: unless-stopped- read_only: true makes the container filesystem read-only; only /tmp and the mounted workspace are writable.
- cap_drop: ALL removes all Linux capabilities; cap_add: NET_BIND_SERVICE is optional and often not needed.
- pids_limit prevents fork bombs.
- mem_limit caps memory usage.
Step 2: Scoped API Tokens for External Calls
Even inside a container, your agent may call external APIs. If you hand it your main API key, it can use your quota, access all your projects, and potentially cause billing surprises. Instead, create a scoped token with only the permissions the agent needs.
For OpenAI, you can create a project-specific API key with usage limits. For other services, use short-lived tokens or OAuth scopes. The key is to treat the agent's credentials as a separate identity with its own permissions.
# Create a new API key with restricted permissions (OpenAI example)
# Log in to platform.openai.com, go to API keys, create a new key,
# and set a hard usage limit (e.g., $10/month).
# Then export it in your environment:
export OPENAI_API_KEY='sk-...restricted...'
# For GitHub tokens, use fine-grained PATs with repo-scoped permissions:
# gh auth token --scopes repo --permissions contents:read- Never reuse your personal API key for agents.
- Set usage limits to cap cost.
- Rotate tokens regularly.
- Use environment variables, not hardcoded secrets.
Step 3: Build a Minimal Agent Loop with Tool Permissions
Now let's write a minimal agent in TypeScript. It will have two tools: read_file and write_file, both restricted to a workspace directory. The agent loop calls the LLM, parses the tool call, and executes it only if the path is within the allowed root.
This is the core of least privilege: the agent can only touch files in the workspace, not your whole disk.
// src/agent.ts
import OpenAI from 'openai';
import fs from 'fs/promises';
import path from 'path';
const client = new OpenAI();
const workspaceRoot = process.env.AGENT_WORKSPACE || '/workspace';
const tools = [
{
type: 'function',
function: {
name: 'read_file',
description: 'Read a file from the workspace',
parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] }
}
},
{
type: 'function',
function: {
name: 'write_file',
description: 'Write a file to the workspace',
parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] }
}
}
];
function safeResolve(p: string) {
const full = path.resolve(workspaceRoot, p);
if (!full.startsWith(workspaceRoot)) throw new Error('Access denied');
return full;
}
async function executeTool(name: string, args: any) {
switch (name) {
case 'read_file': {
const f = safeResolve(args.path);
return await fs.readFile(f, 'utf8');
}
case 'write_file': {
const f = safeResolve(args.path);
await fs.writeFile(f, args.content);
return 'ok';
}
default:
throw new Error('Unknown tool');
}
}
async function run() {
const messages: any[] = [{ role: 'user', content: 'Create a file called hello.txt with the text "Hello, sandbox"' }];
while (true) {
const res = await client.chat.completions.create({ model: 'gpt-4o-mini', messages, tools });
const msg = res.choices[0].message;
messages.push(msg);
if (msg.tool_calls) {
for (const tc of msg.tool_calls) {
const result = await executeTool(tc.function.name, JSON.parse(tc.function.arguments));
messages.push({ role: 'tool', tool_call_id: tc.id, content: result });
}
} else {
console.log(msg.content);
break;
}
}
}
run().catch(console.error);- The safeResolve function prevents path traversal.
- The agent only has two tools, both constrained.
- The loop continues until the model stops calling tools.
Step 4: Add Audit Logging
You need to know what the agent did. Add a simple audit log that records every tool call, the arguments, and the result. Write it to a file outside the agent's workspace, or send it to a remote logging service.
In the example, we append to /var/log/agent-audit.log, which is on a read-only filesystem, so we mount a volume for it.
// src/audit.ts
import fs from 'fs/promises';
const auditFile = process.env.AUDIT_LOG || '/var/log/agent-audit.log';
export async function logAudit(entry: any) {
const line = JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + '\n';
await fs.appendFile(auditFile, line);
}
// In executeTool, call logAudit before and after execution:
// await logAudit({ tool: name, args, result: 'started' });
// const result = ...;
// await logAudit({ tool: name, args, result });services:
agent:
# ... (previous config)
volumes:
- ./workspace:/workspace
- ./logs:/var/log
environment:
- AUDIT_LOG=/var/log/agent-audit.log- Log every tool call, including arguments and results.
- Store logs outside the container so they survive a crash.
- Consider shipping logs to a central aggregator.
Verify It Worked
Build and run the container, then check that the agent can create a file in the workspace but cannot access anything else. Also confirm the audit log contains entries.
# Build and run
cp .env.example .env # set your OPENAI_API_KEY
docker compose up --build -d
# Check the workspace
ls -la workspace/
# Check the audit log
cat logs/agent-audit.log
# Try to access /etc/passwd from inside the container (should fail)
docker exec -it my-agent sh -c 'cat /etc/passwd'- The agent should have created hello.txt in workspace/.
- The audit log should show the write_file call.
- The container should not have read access to host files.
What I Would Do: Recommended Setup
For a production setup, I would combine the above with a few more layers: use a dedicated service account for the agent, enforce network egress restrictions, and add human approval for destructive actions.
Here's a copy-paste starter for a more robust docker-compose with network restrictions and a sidecar for logging.
services:
agent:
build: .
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
networks:
- agent-net
volumes:
- ./workspace:/workspace
- ./logs:/var/log
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- AGENT_WORKSPACE=/workspace
- AUDIT_LOG=/var/log/agent-audit.log
mem_limit: 512m
pids_limit: 100
restart: unless-stopped
networks:
agent-net:
internal: true # no external network access
# To allow outbound HTTPS to the LLM API, use a proxy or add egress rules at the host level.- Use internal network to block outbound connections except through a proxy.
- Set up a human-in-the-loop approval for write or delete operations.
- Use a dedicated service account with only the permissions the agent needs.
- Rotate credentials and review logs regularly.
Troubleshooting
If the agent can't write files, check the workspace volume permissions. The container runs as non-root user 'agent'; ensure the workspace directory is writable by that user.
If the agent can't reach the LLM API, check your network configuration; the internal network blocks outbound traffic by design. You may need to allow specific hosts.
- Permission errors: chown the workspace to the agent user (UID 1000 typically).
- Network errors: add a proxy or remove internal: true for testing.
- Audit log missing: verify the volume mount and that the log file path is writable.
- Path traversal errors: ensure safeResolve uses path.resolve and checks startsWith.
FAQ
Answers to the questions that come up most often on this topic.
- Q: Can I use this pattern with Python agents? A: Yes, the same principles apply; use subprocess with restricted cwd and environment.
- Q: How do I prevent prompt injection from escaping the sandbox? A: Sandboxing limits the blast radius; also validate tool inputs and avoid giving agents dangerous tools.
- Q: What about GUI agents that need a display? A: Run them in a headless X server or use a virtual framebuffer, and still restrict file and network access.
- Q: How do I audit agent actions on the host? A: Use a logging agent or eBPF tools, but ideally keep the agent off the host entirely.
Next Step: Apply This to Your Own Agent
Take the minimal example, extend it with your own tools, and enforce the same boundaries. Start by running the agent in Docker with read-only filesystem and scoped tokens. Then add audit logging and review the logs after each run.
The one command to run right now: docker compose up --build -d and watch the audit log.
Key takeaways
- Apply one concrete change from this post before collecting more reading.
- Prefer browser-side tools when the work involves secrets, tokens, or PII.
- Document the why next to the how so the next reviewer inherits context.
FAQ
- Who is this guide on ai-agents for?
- Working developers who need a practical take on how to give ai agents permissions without giving them your entire computer — not a marketing overview. Skim the sections, apply one tip, then come back when you hit an edge case.
- Do I need an account to use the related tools?
- No. code.live tools run in your browser with no signup. Nothing you paste is uploaded to a server for the client-side utilities linked from this post.
- How often is this article updated?
- This post was published November 22, 2026. Fundamentals stay stable; check linked tool pages and official docs when version-specific behavior matters.