lifectl

Run AI agents like running containers.

lifectl is a CLI tool for pulling, running, and managing AI agents — locally or from a remote registry.

---

✨ Features

• 📦 Pull agents from registry
• ▶️ Run agents locally with named containers
• 🧠 Plug-and-play agent system
• 🔐 Secure authentication via SaaS
• ⚡ Lightweight and fast
• 🔄 Versioned agents
• 📋 Docker-style container lifecycle (run/start/stop/restart/rm)
• 📝 Log rotation with follow mode

---

🚀 Quick Start

Install

npm install -g lifectl

---

📚 Commands

Auth

lifectl auth login       # Login via browser
lifectl auth logout      # Logout

AI Agent — Image

lifectl ai agent pull <name>          # Pull agent from registry
lifectl ai agent pull <name>:<ver>    # Pull specific version
lifectl ai agent push                 # Push agent to registry
lifectl ai agent list                 # List pulled agents
lifectl ai agent rma <name>           # Remove agent (all versions)
lifectl ai agent rma <name>:<ver>     # Remove specific version

AI Agent — Container

lifectl ai agent run <name>                      # Run agent (pull if needed)
lifectl ai agent run <name>:<ver>                # Run specific version
lifectl ai agent run <name> --name <alias>       # Run with a custom container name
lifectl ai agent ps                              # List all containers
lifectl ai agent ps --name <name>                # Filter by agent name or alias
lifectl ai agent ps --status running             # Filter by status: running | stopped
lifectl ai agent ps --name <name> --status stopped  # Combine filters
lifectl ai agent start <containerId>             # Start a stopped container
lifectl ai agent stop <name|alias|containerId>   # Stop a container
lifectl ai agent restart <name|alias|containerId># Restart a container
lifectl ai agent rm <containerId>                # Remove a stopped container
lifectl ai agent logs <name|alias|containerId>   # Show last 50 lines of log
lifectl ai agent logs <name> -n 100              # Show last N lines
lifectl ai agent logs <name> -f                  # Follow log output (auto-stops when process exits)

Named containers

Assign a custom name to a container for easier management:

lifectl ai agent run my-agent --name web
lifectl ai agent logs web
lifectl ai agent stop web

Example output of list

AGENT ID      NAME               VERSION  RUNTIME  PULLED AT
a3f9c12b4e07  hello-world-agent  1.0.0    node     06/04/2026 20:09
b7d2e45f1c08  my-other-agent     2.1.0    python   05/04/2026 15:30

Example output of ps

CONTAINER ID  AGENT ID      NAME                        VERSION  STATUS      PID    STARTED AT
a3f9c12b4e07  b7d2e45f1c08  hello-world-agent (web)     1.0.0    🟢 running  12345  06/04/2026 20:09
c1e8f23a9d05  b7d2e45f1c08  hello-world-agent           1.0.0    ⚫ stopped  12346  05/04/2026 15:30

Allowed runtimes

Agents can only use these runtimes in agent.json scripts:

node  python  python3  deno  bun  npx  ts-node  tsx

---

🏗 Architecture

~/.lifectl/
  agents/
    registry.json          ← image registry
    <name>/<version>/      ← agent files
      agent.json
      .install.lock        ← prevents concurrent installs
  containers/
    containers.json        ← container registry
    <containerId>/         ← per-process folder
      agent.pid
      agent.log
      agent.log.1          ← rotated logs (up to 5 files, 10MB each)

• lifectl CLI → control agents
• Agent Registry → store & version agents
• Container Runtime → isolated process per run
• SaaS Platform → monitoring & management

---

🛣 Roadmap

• CLI foundation
• Authentication (device flow)
• Agent registry (push/publish)
• Agent pull system
• Versioned agents
• Local agent registry (registry.json)
• Agent runtime (local execution)
• Agent process manager (PID-based)
• Docker-style container model (run/start/stop/ps/rm)
• Agent image management (list/rma)
• Log rotation (up to 5 files × 10MB)
• Multi-container per agent
• Named containers (--name)
• Container filtering (ps --name, ps --status)
• Follow log with auto-exit on process death
• SaaS dashboard integration
• Multi-agent workflows
• Agent environment variables support
• Run agent on sandbox

---

🔐 Security

• Token-based authentication
• No credentials stored in plain text
• Runtime whitelist — only node, python, python3, deno, bun, npx, ts-node, tsx are allowed
• PID reuse detection — verifies process start time before kill (Linux)
• tar path traversal protection — blocks .. entries during agent extraction
• Shell metacharacter blocking — ;, &, |, `, $, <, >
• Path traversal protection — agents are isolated under ~/.lifectl/agents/
• PID validation before kill — prevents stale or invalid PID attacks
• Atomic install lock — O_EXCL file lock prevents concurrent dependency installs
• Atomic container writes — write-queue + temp file rename prevents containers.json corruption

---

🧪 Status

⚠️ This project is in early development.

APIs and features may change.

---

🤝 Contributing

Contributions are welcome!

git clone https://github.com/lifetimesoft/lifectl
cd lifectl
npm install
npm run build

---

📄 License

Apache-2.0 license

---

🌐 LifetimeSoft

Building tools for AI automation and agent-based systems.

---

⭐ Support

If you find this project useful, consider giving it a star ⭐