Browser interface and gateway
The same agent from a browser or a phone, served from one port.
Every motita process is also a gateway: it listens on 127.0.0.1:7477 behind a token, and the terminal you are looking at is just one of its clients. A web page or a phone can join the same conversation, with the same skills and the same history.
How the pieces connect
The browser interface
It is served from the gateway's own port, so there is no second server and no cross-origin setup. Open http://127.0.0.1:7477, paste the token once, and you have chat, projects, settings and the skill library. It installs as an app (PWA) and is compiled into the binary.
The token is read from ~/.motita/gateway.token and printed by motita gateway start.
Memory
The Memory button in the sidebar opens what you and the agent want to remember, as plain Markdown files: collections (the first folder, so engineering and HR never mix), entries with an author and a date, [[wiki links]], a graph of the links and a search. The search is hybrid: words, a local holographic vector memory and, if you configure embeddings, a neural model, merged into one ranking. It matches small passages but answers with the whole section they belong to, can follow links to related entries, and the agent cites the entry it relies on. The files are ordinary .md in ~/.motita/memory (the old notes folder is renamed on the first start), so you can open that same folder in Obsidian.
Running the gateway
motita gateway start # start the service and wait until it answers
motita gateway status # is one running, where, and which build
motita gateway stop
motita gateway setup # where it answers: this machine, the LAN, everywhere
If a gateway is already running, motita attaches to it and never shuts it down. If none is running, it brings one up for itself and stops it when you leave.
The two halves apart
# on the machine that runs the commands
motita -serve -gateway 127.0.0.1:7477
# anywhere else: no sandbox, no agent in this process
motita -connect 127.0.0.1:7477 -tui
A -connect client is only an interface, so it runs on a laptop, a tablet or a phone through a tunnel. Reaching it from other machines safely is covered in Network and remote access.
Follow a run from code
Besides the WebSocket, POST /v1/sessions/{id}/task starts a task and answers with a stream of server-sent events: progress lines while it works, then done with the result, or error. The run belongs to the gateway, not to the connection, so a client that drops can attach again with GET /v1/sessions/{id}/events?from=N.
A browser's EventSource can only send GET, so read the stream with fetch, as here (set MOTITA_TOKEN first):
const res = await fetch("http://127.0.0.1:7477/v1/sessions/default/task", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.MOTITA_TOKEN, // the gateway token: motita gateway start -token-only
"Content-Type": "application/json",
},
body: JSON.stringify({ task: "run the tests and fix what fails" }),
});
if (!res.ok) throw new Error("HTTP " + res.status);
let event = "";
let buffer = "";
for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) {
buffer += chunk;
const lines = buffer.split("\n");
buffer = lines.pop() ?? "";
for (const line of lines) { // one line per event: the name, then its JSON
if (line.startsWith("event: ")) {
event = line.slice(7);
} else if (line.startsWith("data: ")) {
const data = JSON.parse(line.slice(6));
if (event === "progress") console.log("-", data.text); // a progress line, as it happens
if (event === "done") console.log(data.result); // the turn's final result
if (event === "error") throw new Error(data.error); // the run ended in a failure
}
}
}import { env } from "node:process";
interface Data {
text?: string;
result?: string;
error?: string;
}
const res = await fetch("http://127.0.0.1:7477/v1/sessions/default/task", {
method: "POST",
headers: {
Authorization: "Bearer " + env.MOTITA_TOKEN, // the gateway token: motita gateway start -token-only
"Content-Type": "application/json",
},
body: JSON.stringify({ task: "run the tests and fix what fails" }),
});
if (!res.ok || !res.body) throw new Error("HTTP " + res.status);
let event = "";
let buffer = "";
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
for (let part = await reader.read(); !part.done; part = await reader.read()) {
buffer += part.value;
const lines = buffer.split("\n");
buffer = lines.pop() ?? "";
for (const line of lines) { // one line per event: the name, then its JSON
if (line.startsWith("event: ")) {
event = line.slice(7);
} else if (line.startsWith("data: ")) {
const data = JSON.parse(line.slice(6)) as Data;
if (event === "progress") console.log("-", data.text); // a progress line, as it happens
if (event === "done") console.log(data.result); // the turn's final result
if (event === "error") throw new Error(data.error); // the run ended in a failure
}
}
}# pip install requests
import json
import os
import requests
res = requests.post(
"http://127.0.0.1:7477/v1/sessions/default/task",
headers={"Authorization": "Bearer " + os.environ["MOTITA_TOKEN"]}, # the gateway token: motita gateway start -token-only
json={"task": "run the tests and fix what fails"},
stream=True,
)
res.raise_for_status()
res.encoding = "utf-8"
event = ""
for line in res.iter_lines(decode_unicode=True): # one line per event: the name, then its JSON
if line.startswith("event: "):
event = line[7:]
elif line.startswith("data: "):
data = json.loads(line[6:])
if event == "progress":
print("-", data["text"]) # a progress line, as it happens
elif event == "done":
print(data["result"]) # the turn's final result
elif event == "error":
raise SystemExit(data["error"]) # the run ended in a failurepackage main
import (
"bufio"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
"strings"
)
type Data struct {
Text string `json:"text"`
Result string `json:"result"`
Error string `json:"error"`
}
func main() {
body := strings.NewReader(`{"task":"run the tests and fix what fails"}`)
req, err := http.NewRequest(http.MethodPost, "http://127.0.0.1:7477/v1/sessions/default/task", body)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("MOTITA_TOKEN")) // the gateway token: motita gateway start -token-only
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
log.Fatal("HTTP ", res.Status)
}
scanner := bufio.NewScanner(res.Body)
scanner.Buffer(make([]byte, 0, 64*1024), 1<<20)
event := ""
for scanner.Scan() { // one line per event: the name, then its JSON
line := scanner.Text()
if name, ok := strings.CutPrefix(line, "event: "); ok {
event = name
} else if raw, ok := strings.CutPrefix(line, "data: "); ok {
var data Data
if err := json.Unmarshal([]byte(raw), &data); err != nil {
log.Fatal(err)
}
switch event {
case "progress":
fmt.Println("-", data.Text) // a progress line, as it happens
case "done":
fmt.Println(data.Result) // the turn's final result
case "error":
log.Fatal(data.Error) // the run ended in a failure
}
}
}
}// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use serde_json::{json, Value};
use std::io::{BufRead, BufReader};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let token = std::env::var("MOTITA_TOKEN")?; // the gateway token: motita gateway start -token-only
let res = reqwest::blocking::Client::builder()
.timeout(None) // a run can take minutes
.build()?
.post("http://127.0.0.1:7477/v1/sessions/default/task")
.bearer_auth(token)
.json(&json!({ "task": "run the tests and fix what fails" }))
.send()?
.error_for_status()?;
let mut event = String::new();
for line in BufReader::new(res).lines() { // one line per event: the name, then its JSON
let line = line?;
if let Some(name) = line.strip_prefix("event: ") {
event = name.to_string();
} else if let Some(raw) = line.strip_prefix("data: ") {
let data: Value = serde_json::from_str(raw)?;
match event.as_str() {
"progress" => println!("- {}", data["text"].as_str().unwrap_or_default()), // a progress line, as it happens
"done" => println!("{}", data["result"].as_str().unwrap_or_default()), // the turn's final result
"error" => return Err(data["error"].as_str().unwrap_or("error").into()), // the run ended in a failure
_ => {}
}
}
}
Ok(())
}More than one conversation
A gateway holds many sessions at once. The model belongs to the session, so changing it affects that conversation only, and survives a restart. Other programs can drive the same sessions over HTTP, server-sent events or a WebSocket protocol; the reference lists every endpoint.