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

# Built-in managed integration
agent install openclaw

# 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"}'

Manage OpenClaw

agent install openclaw
agent info openclaw
agent run openclaw --input '{"action":"status"}'
agent update openclaw
agent remove openclaw
# or remove wrapper + upstream package:
agent uninstall openclaw

OpenClaw is a built-in managed external integration. UseAgents tracks wrapper state separately from the upstream OpenClaw binary, installs upstream OpenClaw through the official installer, updates with the official update flow, and can optionally uninstall upstream OpenClaw too.

UseAgents never exposes or owns an openclaw executable. agent ... manages the wrapper; plain openclaw ... remains the upstream OpenClaw CLI.

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 uninstall openclaw      # Uninstall upstream OpenClaw too
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

# Manage the built-in OpenClaw integration
node dist/index.js install openclaw
node dist/index.js info openclaw
node dist/index.js run openclaw --input '{"action":"status"}'

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.