https://github.com/icholy/xagent
https://github.com/icholy/xagent
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/icholy/xagent
- Owner: icholy
- Created: 2026-01-02T21:46:33.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2026-05-17T16:32:56.000Z (3 months ago)
- Last Synced: 2026-05-17T16:54:31.925Z (3 months ago)
- Language: Go
- Size: 3.81 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# XAGENT
Runs coding agents (Claude Code, Codex, Cursor, GitHub Copilot) inside remote sandboxes.
## Features
- **Self-hosted runners** - Run agents on your own infrastructure inside Docker containers
- **Third-party integrations** - Interact with agents via GitHub and Jira comments
- **MCP server** - Create and manage tasks from Claude Code, Cursor, or any MCP client
## Web UI
## Quick Start
Install `xagent` cli:
```bash
mise run install
```
Download the pre-built binaries (if needed):
```bash
xagent download
```
Authenticate your local client:
```bash
xagent setup
```
Update the `workspaces.yml` file (see examples below):
```bash
vim ~/.config/xagent/workspaces.yaml
```
Start the local runner:
```bash
xagent runner
```
Create and monitor tasks via the Web UI.
Open: https://xagent.choly.ca/
## Workspace Examples
See [examples/workspaces/](examples/workspaces/) for workspace configuration examples:
- [claude.yml](examples/workspaces/claude.yml) - Claude Code
- [codex.yml](examples/workspaces/codex.yml) - OpenAI Codex
- [cursor.yml](examples/workspaces/cursor.yml) - Cursor Agent
- [copilot.yml](examples/workspaces/copilot.yml) - GitHub Copilot
- [mcp-server.yml](examples/workspaces/mcp-server.yml) - MCP server configuration
- [private-repo.yml](examples/workspaces/private-repo.yml) - Cloning private repositories
- [dummy.yml](examples/workspaces/dummy.yml) - Dummy agent for testing
## Docker Compose Runner
See [examples/runner/](examples/runner/) for running the runner as a Docker Compose service with a pull-through registry cache.
## Debugging
View container logs:
```bash
xagent logs -f
```
Set `verbose: true` on a workspace's agent to bypass the CLI output parser and
log every raw line. Useful when the parser is hiding details (errors,
intermediate output, tool-use payloads) you want to inspect via `xagent logs`.
```yaml
agent:
type: claude
verbose: true
```
Get a shell to a task container:
```bash
xagent shell
```
List task containers:
```bash
xagent containers
```
## Local Development
```bash
# Start server and postgres locally
docker compose up -d
# Run the FE
cd webui
pnpm install
pnpm run dev
```
The local server runs with `--no-auth`, but the runner still requires an API key.
Create one in the local Web UI at http://localhost:5173/ui/keys/new, then start the runner:
```bash
xagent runner --server http://localhost:6464 -key
```
### Build
```bash
mise run build # Build main + prebuilt binaries (linux amd64/arm64)
mise run generate # Generate protobuf code
go build # Build main binary only
```
## Events
Agents can attach **links** to their tasks for external resources they create (PRs, Jira issues, etc.). Links created with `subscribe=true` act as subscriptions. When someone comments on the resource, the agent is automatically restarted to respond.
## Architecture
## Schema
