---
title: "Node.js and ACP · Alran Code Docs"
url: https://alran.dev/en/docs/sdk
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Automate

# Node.js and ACP

Drive Alran Code from your own program, or plug it into any editor that speaks the Agent Client Protocol.

On this page

[How do I drive Alran Code from my own program?](#entry) [From Node.js](#node) [ACP](#acp) [Change the agent's prompt](#prompt) [Common questions](#faq)

## How do I drive Alran Code from my own program? {#entry}

| Entry point | Command | Use it for |
| Interactive TUI | `alran [prompt]` | Working with the agent yourself |
| Headless | `alran exec [prompt]` | Scripts, CI, batch work, evaluations |
| ACP | `alran acp` | Editors and clients that speak the Agent Client Protocol |

## From Node.js {#node}

`alran exec --output-format stream-json` writes one JSON event per line, which any language can read:

```js
import { spawn } from 'node:child_process';
import { createInterface } from 'node:readline';

const run = spawn('alran', ['exec', '--output-format', 'stream-json', 'Fix the failing test']);
for await (const line of createInterface({ input: run.stdout })) {
  const event = JSON.parse(line);
  console.log(event.type);
}
```

## ACP {#acp}

```bash
alran acp
```

Runs Alran Code as an Agent Client Protocol server over stdio. An editor starts it and talks to it; tools, permissions, skills, plugins, MCP, subagents, goals and sessions behave exactly as in the terminal, because the same runtime runs them. The [VS Code extension](https://alran.dev/en/docs/vscode) works this way.

## Change the agent's prompt {#prompt}

Every entry point takes the same switches for one process:

| Option | What it does |
| `--append-system-prompt <text>` | Add text after the agent's identity |
| `--append-system-prompt-file <path>` | The same, from a file |
| `--system-prompt <text>` | Replace the identity section |
| `--system-prompt-file <path>` | The same, from a file |

Project instructions (`AGENTS.md`), the environment, memory and skills stay in either case.

## Common questions {#faq}

How do I call Alran Code from my own program?

There are three ways in: the interactive TUI with alran, the headless mode with alran exec for scripts, CI and batch work, and the Agent Client Protocol with alran acp for editors and clients that speak it. For a script, spawn alran exec --output-format stream-json and read its output line by line: it writes one JSON event per line, which any language can read.

What is the Agent Client Protocol and when should I use it?

alran acp runs Alran Code as an Agent Client Protocol server over stdio. An editor starts it and talks to it, and tools, permissions, skills, plugins, MCP, subagents, goals and sessions behave exactly as in the terminal, because the same runtime runs them. The VS Code extension works this way.

How do I change the system prompt of the agent?

Every entry point takes the same switches for one process: --append-system-prompt and --append-system-prompt-file add text after the identity of the agent, --system-prompt and --system-prompt-file replace that identity section. Project instructions in AGENTS.md, the environment, memory and skills stay in either case.

[PreviousHeadless and CI](https://alran.dev/en/docs/headless) [NextVS Code extension](https://alran.dev/en/docs/vscode)
