Skip to main content

​
Agent Commands

Manage the lifecycle of OpenFang agents: spawn from templates or custom manifests, list running agents, chat interactively, and terminate agents.

​
openfang agent new

Spawn an agent from a built-in template. 
openfang agent new [<TEMPLATE>]

​
Arguments

ArgumentDescription
<TEMPLATE>Template name (e.g., coder, assistant, researcher). If omitted, displays an interactive picker.

​
Behavior

  • Templates are discovered from:
    • The repo agents/ directory (dev builds)
    • ~/.openfang/agents/ (installed)
    • OPENFANG_AGENTS_DIR (env override)
  • Each template is a directory containing an agent.toml manifest
  • Daemon mode: Sends POST /api/agents with the manifest. Agent is persistent.
  • Standalone mode: Boots an in-process kernel. Agent is ephemeral.

​
Examples

# Show list of available templates
openfang agent new

​
Output

Agent spawned successfully!
  ID:   a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Name: coder

​
openfang agent spawn

Spawn an agent from a custom manifest file. 
openfang agent spawn <MANIFEST>

​
Arguments

ArgumentDescription
<MANIFEST>Path to an agent manifest TOML file.

​
Behavior

  • Reads and parses the TOML manifest file
  • Daemon mode: Sends the raw TOML to POST /api/agents
  • Standalone mode: Boots an in-process kernel and spawns the agent locally

​
Example Manifest

Create a file my-agent.toml:
my-agent.toml
name = "my-assistant"
version = "0.1.0"
description = "A helpful assistant"
author = "you"
module = "builtin:chat"

[model]
provider = "groq"
model = "llama-3.3-70b-versatile"

[capabilities]
tools = ["file_read", "file_list", "web_fetch"]
memory_read = ["*"]
memory_write = ["self.*"]

​
Examples

# Spawn from local manifest
openfang agent spawn ./my-agent.toml

# Spawn from agents directory
openfang agent spawn ~/.openfang/agents/custom-agent/agent.toml

# Spawn the hello-world template
openfang agent spawn agents/hello-world/agent.toml

​
openfang agent list

List all running agents. 
openfang agent list [--json]

​
Options

OptionDescription
--jsonOutput as JSON array for scripting.

​
Output

Daemon mode (with provider/model info): 
ID                                     NAME             STATE      PROVIDER     MODEL
---------------------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-...                     hello-world      Running    groq         llama-3.3-70b-versatile
b2c3d4e5-f6a7-...                     coder            Running    anthropic    claude-sonnet-4-20250514
Standalone mode: 
ID                                     NAME             STATE      CREATED
---------------------------------------------------------------------------------
a1b2c3d4-e5f6-...                     hello-world      Running    2026-03-07 14:23:45

​
Examples

openfang agent list

​
openfang agent chat

Start an interactive chat session with a specific agent. 
openfang agent chat <AGENT_ID>

​
Arguments

ArgumentDescription
<AGENT_ID>Agent UUID. Obtain from openfang agent list.

​
Behavior

  • Opens a REPL-style chat loop
  • Type messages at the you> prompt
  • Agent responses display at the agent> prompt, followed by token usage and iteration count
  • Type exit, quit, or press Ctrl+C to end the session

​
Example Session

openfang agent chat a1b2c3d4-e5f6-7890-abcd-ef1234567890
Output: 
Chat session started (daemon mode). Type 'exit' or Ctrl+C to quit.

you> Hello! What can you do?

agent> I'm the hello-world agent running on OpenFang. I can:
- Read files from the filesystem
- List directory contents
- Fetch web pages

Try asking me to read a file or look up something on the web!

  [tokens: 142 in / 87 out | iterations: 1]

you> List the files in the current directory

agent> Here are the files in the current directory:
- Cargo.toml
- Cargo.lock
- README.md
- agents/
- crates/
- docs/

  [tokens: 98 in / 56 out | iterations: 1]

you> exit
Chat session ended.

​
openfang agent kill

Terminate a running agent. 
openfang agent kill <AGENT_ID>

​
Arguments

ArgumentDescription
<AGENT_ID>Agent UUID to terminate.

​
Example

openfang agent kill a1b2c3d4-e5f6-7890-abcd-ef1234567890
Output: 
Agent a1b2c3d4-e5f6-... terminated successfully.

​
openfang chat (Quick Chat Alias)

Quick alias for starting a chat session. Works with or without a daemon. 
openfang chat [<AGENT>]

​
Arguments

ArgumentDescription
<AGENT>Optional agent name or UUID.

​
Behavior

  • Daemon mode: Finds the agent by name or ID among running agents. If no agent name is given, uses the first available agent. If no agents exist, suggests openfang agent new.
  • Standalone mode (no daemon): Boots an in-process kernel and auto-spawns an agent from templates. Searches for an agent matching the given name, then falls back to assistant, then to the first available template.
This is the simplest way to start chatting — it works with or without a daemon.

​
Examples

# Chat with the first available agent
openfang chat

​
openfang agent set

Set an agent property (e.g., model). 
openfang agent set <AGENT_ID> <FIELD> <VALUE>

​
Arguments

ArgumentDescription
<AGENT_ID>Agent UUID.
<FIELD>Field to set (currently supports model).
<VALUE>New value.

​
Examples

# Switch agent to use Claude Sonnet
openfang agent set a1b2c3d4-e5f6 model claude-sonnet-4-20250514

# Switch agent to use GPT-4o
openfang agent set a1b2c3d4-e5f6 model gpt-4o

​
Complete Workflow Example

# 1. List available templates
openfang agent new

# 2. Spawn the coder agent
openfang agent new coder

# 3. List running agents and copy the ID
openfang agent list

# 4. Chat with the agent
openfang agent chat a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 5. Terminate the agent when done
openfang agent kill a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Quick Chat Workflow

# Simplest workflow: just start chatting
openfang chat

# Or specify an agent by name
openfang chat coder

​
Next Steps

Workflow Commands

Chain multiple agents together

Skill Commands

Extend agents with new capabilities

Config Commands

Configure default models and providers

CLI Overview

Back to CLI overview

Build docs developers (and LLMs) love

Get started for freeTalk to us