UseAgents

Local agent package runner for AI agents

UseAgents (agent) is a CLI tool that lets you install, manage, and run AI agents locally — like a package manager, but for autonomous agents.

Why UseAgents?

Most AI agent platforms require cloud infrastructure or complex setup. UseAgents brings the simplicity of package managers to AI agents:

• Install agents like packages: agent install github:org/agent
• Run them locally: agent run my-agent --input '{"task": "write code"}'
• Version management: Multiple versions installed, one active
• Permission enforcement: Agents declare what they need, you control access
• Secret management: Store API keys securely, inject only when needed

Quick Start

Installation

npm install -g @thesethrose/useagents

Install an Agent

# From a local folder
agent install ./examples/hello-world

# From GitHub (shorthand)
agent install github:your-org/hello-world

# From any git URL
agent install https://github.com/your-org/hello-world

Run an Agent

agent run hello-world --input '{"name": "Developer"}'

Run in Sandbox Mode

agent run hello-world --sandbox --input '{"name": "Developer"}'

Sandbox mode runs agents in an isolated Docker container with:

• No network access
• Read-only filesystem
• Memory and CPU limits
• Tool restrictions

Manage Agents

agent list                    # List installed agents
agent info hello-world        # Show agent details
agent update hello-world      # Update to latest version
agent remove hello-world      # Remove an agent
agent logs hello-world        # View execution history

Writing an Agent

Agents are just folders with an agent.yaml manifest and an entrypoint.

Minimal Agent

# agent.yaml
name: hello-world
version: 1.0.0
description: A simple hello world agent
runtime:
  type: javascript
  entrypoint: ./dist/index.js
permissions:
  network: false
  filesystem:
    read: []
    write: []
  secrets: []
tools:
  - echo.text

// dist/index.js
export async function run(input, ctx) {
  const name = input?.name || "World";
  const echo = await ctx.tools["echo.text"]({ text: `Hello, ${name}!` });
  return { message: echo.text };
}

Agent Context

When an agent runs, it receives a context object (ctx) with:

Manifest Reference

name: hello-world                 # kebab-case identifier
version: 1.0.0                    # semver

description: "A simple hello world agent"

runtime:
  type: javascript                # runtime type (currently: javascript)
  entrypoint: ./dist/index.js     # entry file

model:                            # optional LLM config
  provider: openrouter            # model provider
  model: anthropic/claude-3.7-sonnet

permissions:                      # what the agent needs
  network: false                  # internet access?
  # or restrict to specific domains:
  # network:
  #   enabled: true
  #   domains: ["api.example.com", "*.openai.com"]
  filesystem:
    read: []                      # paths allowed for reading
    write: []                     # paths allowed for writing
  secrets:
    - OPENROUTER_API_KEY          # required secrets
  sandbox:                        # optional sandbox policy
    enabled: false
    tools:                        # tools allowed in sandbox mode
      - echo.text

tools:                            # available tools
  - echo.text                     # echo input back
  - http.fetch                    # make HTTP requests
  - fs.readText                   # read files
  - fs.writeText                  # write files

Architecture

~/.useagents/
├── runtimes/          # Versioned agent installs
│   └── hello-world/
│       └── 1.0.0/
│           ├── agent.yaml
│           └── dist/
│               └── index.js
├── active/            # Symlinks to active versions
│   └── hello-world -> ../runtimes/hello-world/1.0.0
├── state/
│   ├── installs.json   # Install registry
│   ├── logs.jsonl      # Execution history
│   ├── audit.jsonl     # File/network access audit log
│   └── permissions.json # Granted permission records
├── secrets/
│   └── secrets.json   # Encrypted secrets (0600 perms)
└── cache/             # Git clone cache

CLI Reference

Development

# Clone the repo
git clone https://github.com/thesethrose/useagents.git
cd useagents

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js --help

# Test with example agent
node dist/index.js install ./examples/hello-world
node dist/index.js run hello-world

Security Model

1. Manifest declarations: Agents must declare all permissions in agent.yaml
2. Permission prompts: First run requires explicit user approval of requested permissions
3. Secret isolation: Secrets are stored separately, injected only when declared
4. Filesystem sandboxing: Agents can only access declared paths
5. Network control: Internet access is opt-in per agent, with domain allowlisting
6. Audit logging: All executions and file/network access logged to ~/.useagents/state/
7. Docker sandboxing: Optional containerized execution with resource limits and tool restrictions

Roadmap

See CHANGELOG.md for planned features.

Highlights:

• v0.2.0: Sandboxed runtime (Deno/QuickJS), permission prompts
• v0.3.0: Web registry, agent search, semver resolution
• v0.4.0: Python runtime, Docker isolation, background execution
• v0.5.0: VS Code extension
• v1.0.0: Stable API, comprehensive tests, official docs

Contributing

Contributions welcome! Please read our Contributing Guide first.

License

This project is licensed under the MIT License.