https://github.com/askalf/agent
Connect any device to the askalf fleet. WebSocket bridge that dispatches autonomous agent tasks to your machine.
https://github.com/askalf/agent
agent-cli ai ai-agents autonomous-agents claude device-bridge fleet nervous-system npm remote-execution self-hosted service-manager typescript websocket
Last synced: 12 days ago
JSON representation
Connect any device to the askalf fleet. WebSocket bridge that dispatches autonomous agent tasks to your machine.
- Host: GitHub
- URL: https://github.com/askalf/agent
- Owner: askalf
- License: mit
- Created: 2026-03-01T01:27:48.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-10T01:05:03.000Z (13 days ago)
- Last Synced: 2026-06-10T03:05:56.468Z (13 days ago)
- Topics: agent-cli, ai, ai-agents, autonomous-agents, claude, device-bridge, fleet, nervous-system, npm, remote-execution, self-hosted, service-manager, typescript, websocket
- Language: TypeScript
- Homepage: https://askalf.org
- Size: 251 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# @askalf/agent
connect any device to your askalf fleet
[](https://www.npmjs.com/package/@askalf/agent)
[](https://nodejs.org)
[](LICENSE)
[](https://github.com/askalf/agent/actions)
**[askalf.org](https://askalf.org)** · **[@ask_alf](https://x.com/ask_alf)** · **[Changelog](CHANGELOG.md)**
---
## What this is
`@askalf/agent` is the device-side half of an [askalf](https://github.com/askalf/platform) workforce. You run it on a machine you want the fleet to be able to act on — a server, a laptop, a remote box — and it opens a persistent WebSocket to your askalf forge. From then on, agents in the fleet can run shell commands or Claude Code on that machine, see what's installed, and stream results back.
It's not a chat client, an MCP server, or an autonomous coder. It's a connector — the substrate side of "agents can do real things on real computers."
---
## Install
```bash
npm install -g @askalf/agent
```
Requires Node 22+. For Claude Code execution, install `@anthropic-ai/claude-code` globally as well.
## One-command setup
```bash
askalf-agent connect --url ws://your-forge:3005 --name laptop --install
```
Writes config, registers with the forge, installs a system service that auto-starts. Close the terminal — the agent keeps running.
---
## Commands
| Command | What it does |
|---|---|
| `connect ` | Connect to a forge. Add `--install` to also register as a service. |
| `disconnect` | Stop the running daemon. |
| `status` | Show connection + service state. |
| `scan` | List the device's discoverable capabilities (CPU, RAM, installed tools, Claude Code presence). |
| `doctor` | Diagnose common setup issues and offer fixes. |
| `daemon` | Run in foreground. Mostly useful for debugging — `--install` is the normal path. |
| `install-service` | Install the service after a `connect` without `--install`. |
| `uninstall-service` | Remove the service. |
### Options
| Flag | Description | Default |
|---|---|---|
| `--url ` | Forge WebSocket URL | `wss://askalf.org` |
| `--name ` | Device display name in the dashboard | system hostname |
| `--install` | Install as a service after connecting | — |
| `-v, --version` | Print version | — |
| `-h, --help` | Print help | — |
---
## Service install
| OS | Backend | Auto-start |
|---|---|---|
| Linux | systemd unit | on boot |
| macOS | launchd plist | on login |
| Windows | Scheduled Task (or `nssm` if installed) | on login |
---
## How it works
```
your device askalf forge
┌──────────────┐ ┌──────────────────────┐
│ askalf-agent │ ──── wss ──────► │ dispatcher │
│ │ ◄─── task ────── │ agent fleet │
│ shell │ ──── stream ───► │ dashboard / discord │
│ Claude Code │ ──── result ───► │ │
│ device tools│ └──────────────────────┘
└──────────────┘
```
- **Heartbeat** every 30s with memory and uptime.
- **Auto-reconnect** with backoff after a disconnect.
- **Capability scan** on registration and on demand — reports CPU, RAM, OS, and presence of `git`, `docker`, `node`, `npm`, `python`, `gh`, `claude`, and more.
- **5-minute subprocess timeout** by default per task.
- **Streaming output** — the dashboard sees what the task prints, line by line, while it's still running. A final result with token + cost numbers follows.
---
## Programmatic usage
```typescript
import os from 'node:os';
import { AgentBridge, scanCapabilities } from '@askalf/agent';
const bridge = new AgentBridge({
apiKey: process.env.ASKALF_AGENT_KEY!,
url: 'wss://your-forge.example.com',
deviceName: 'edge-laptop',
hostname: os.hostname(),
os: `${os.type()} ${os.release()}`,
capabilities: scanCapabilities(),
});
await bridge.connect();
```
Most users want the CLI. This is for embedding the connector in something larger.
---
## Known limitations
Building in public — real today:
- **systemd restart can corrupt the stored apiKey (Linux).** A `systemctl restart askalf-agent` re-encrypts the config and, in some cases, leaves the apiKey unrecoverable. Until the upstream fix lands, recover with `askalf-agent disconnect && askalf-agent connect --install`.
- **Per-user/machine key binding.** Keys are bound to the user that ran `connect` on the machine that ran it. Switching Linux users on the same box means minting a new key, not reusing the old one.
- **Older `ws` versions reject base64-encoded API keys as subprotocols.** If you embed `AgentBridge` in a project with an older `ws`, pin to `^8.20.0` or move the key to the `Authorization` header.
---
## Requirements
- Node 22+
- [`@anthropic-ai/claude-code`](https://www.npmjs.com/package/@anthropic-ai/claude-code) globally installed, if you want the fleet to run Claude Code tasks here
- A reachable askalf forge (`npx create-askalf` or `curl -fsSL https://get.askalf.org | bash`)
---
## Related projects
| Project | What it does |
|---|---|
| **[askalf/platform](https://github.com/askalf/platform)** | The forge + dashboard the agent connects to. |
| **[@askalf/dario](https://github.com/askalf/dario)** | Local LLM router. Use your Claude Max subscription as an API. |
| **[@askalf/hands](https://github.com/askalf/hands)** | Computer-use SDK. Agents drive a browser. |
| **[@askalf/deepdive](https://github.com/askalf/deepdive)** | Deep-research SDK with citation tracking. |
---
## License
MIT — see [LICENSE](LICENSE).
---
**[askalf.org](https://askalf.org)** · **[npm](https://www.npmjs.com/package/@askalf/agent)** · **[@ask_alf](https://x.com/ask_alf)**
---
## Built by Sprayberry Labs
This is one of the open-source building blocks from **[Sprayberry Labs](https://sprayberrylabs.com)** — an independent studio (Atlanta, GA) that ships bespoke software and **fixed-price code & security audits**, delivered with the AI workforce these tools are part of.
**Got a codebase that needs an expert read?** → **[Scan a repo — free mini-audit](https://sprayberrylabs.com)**, or see the **$1,500 fixed-price Audit** and build Sprints. · [sprayberrylabs.com](https://sprayberrylabs.com) · hello@sprayberrylabs.com