Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@ Needs Rust (cargo) and, on macOS, the Xcode command-line tools (swiftc).
```sh
./install.sh # macOS: LaunchX.app into ~/Applications, lx linked into ~/.local/bin
lx up # start the launcher now and at every login
lx add ~/code/my-app # register a service by its directory
lx install AutoPhd-org/schedule-everything # install an app from its repository
lx add ~/code/my-app # or register one that is already on this computer
```

On Linux `install.sh` copies `lx` into `~/.local/bin`; use the browser page at `http://launchx.localhost:7600/` (`lx open`).
Expand All @@ -86,6 +87,7 @@ On Linux `install.sh` copies `lx` into `~/.local/bin`; use the browser page at `
Open **LaunchX** from Launchpad, Spotlight or `~/Applications`.

- **Main window:** every service as a card with its status, health, summary, version and port, plus Open, Start, Stop, Restart and Logs buttons. It is the launcher's web page, signed in automatically.
- **Install app** takes a repository or folder, shows what installing it will run, and installs it. Apps installed this way get **Update** and **Uninstall** on their card, and a note when their repository has new commits.
- **Open** sends a service's page to your default browser, already signed in (starting the service first if needed). After that, a bookmark such as `http://vmc.localhost:7600/` signs in on its own for 30 days.
- **Menu bar (paper plane):** each service with a coloured dot and Open / Start / Stop / Restart, without opening the window.
- **When the launcher is not running,** the window offers a Start button (it runs `lx up`).
Expand All @@ -100,6 +102,9 @@ LaunchX is the only app: services stay in the browser, where they get tabs, book
| `lx start <id>` / `lx stop <id>` / `lx restart <id>` | Control a service. Start brings up what it requires; stop first stops what requires it. Services you started come back when the launcher restarts (at login, after an update) until you stop them. |
| `lx open [id]` | Open the launcher, or a service's page, in the browser. |
| `lx logs <id> [-f] [-n N]` | Captured output, including the launcher's own notes (`[launchx]`). |
| `lx install <source>` | Install an app from a git URL, `owner/repo` on GitHub, or a folder: clone it (a folder stays where it is), run the installer its `launchx.toml` names, register it. Asks first; `--yes` doesn't. With no source, lists what is installed. |
| `lx update [<name>…]` | Pull each installed app and, when there is something new, run its installer again, restarting what was running. `--check` only reports. |
| `lx uninstall <name>` | Stop the app, run its uninstaller, unregister it and delete the checkout LaunchX cloned. Your data stays, and it says where. |
| `lx add <path>` / `lx rm <id>` | Register or unregister a manifest. `rm` removes the link in `~/.launchx/services`, never the manifest. |
| `lx check <id>` | Start a temporary copy on a spare port and test it against the level it claims. |
| `lx state` | The launcher's full state document as JSON. |
Expand Down Expand Up @@ -154,6 +159,8 @@ run/<id>.json URL, token and pid of each running service (mode 0600)
logs/<id>.log captured output, rotated at 5 MB
agents/skills/ skills published to your agents, linked from their skill folders
memory/ your shared memory: pages/, history/ and log.jsonl
sources/<name>/ checkouts lx install cloned
installs.json what lx install installed, from where, at which commit
state.json assigned ports and tokens, the session secret, and the agents and memory switches (mode 0600)
```

Expand Down
61 changes: 60 additions & 1 deletion SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,35 @@ wants = "write"
reason = "Keeps your schedule page current and suggests tasks that fit your profile"
```

### 4.9 Install fields

The optional top-level `[install]` table says how to build and install the project from a checkout of its repository, so that `lx install` and `lx update` can do it (§10.8). LaunchX reads it only from the `launchx.toml` at the root of a checkout; a copy of the manifest elsewhere may carry it and it is ignored there.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `run` | array of strings | none | The installer: command and arguments, run in the checkout. |
| `uninstall` | array of strings | none | Undoes what `run` did (commands, launch agents, installed files) and keeps the user's data. |
| `needs` | array of strings | empty | Executables that must be on `PATH` before `run`, for example `cargo`. |
| `data` | array of strings | empty | Where the app keeps the user's data. Shown on uninstall, and what to copy when moving to another machine. LaunchX never deletes it. |

```toml
[install]
run = ["./install.sh", "--yes"]
uninstall = ["./uninstall.sh"]
needs = ["cargo"]
data = ["~/.schedule_management"]
```

An installer:

- MUST NOT prompt. Its standard input is closed.
- MUST be safe to run again over an earlier install, since that is how updates run, and MUST keep the user's data.
- MAY register a manifest of its own with `lx add`, for example one written next to the files it installed. When it has registered none of the services the checkout's manifest defines, LaunchX registers the checkout's manifest.

It runs with the user's login environment, the directory of `lx` first on `PATH`, `LAUNCHX_HOME`, and `LAUNCHX_INSTALL` set to `install` or `update`.

Without `run`, installing only registers the checkout's manifest. That suits a project that runs from its checkout.

## 5. Process contract (level 1)

### 5.1 Foreground
Expand Down Expand Up @@ -337,6 +366,8 @@ run/<id>.json one per running service, mode 0600
logs/<id>.log captured output, rotated
agents/skills/ skills published to agents (§10.7)
memory/ the user's shared memory (§12.1)
sources/<name>/ checkouts that lx install cloned (§10.8)
installs.json what was installed from where (§10.8)
state.json assigned ports and tokens, which services the user left running,
which are discoverable by agents and what each may do with
memory; mode 0600
Expand Down Expand Up @@ -417,6 +448,12 @@ POST /api/memory/agents body {"access": "none"|"read"|"write"} (
* /api/memory/… the shared memory (§12.4)
GET /api/services/{id}/logs?tail=200
GET /api/agents what agents are told (§10.7)
POST /api/install/plan body {"source", "name"?}: fetch and say what installing would do (§10.8)
POST /api/install body {"source", "name"?}: install, as a job
POST /api/packages/{name}/update body {"force"?}: update, as a job
POST /api/packages/{name}/uninstall remove, as a job
POST /api/packages/check look for updates now
GET /api/install/log?tail=200 output of the current or last job
POST /api/link one-time sign-in link; body {"service": id?, "next": path?}
POST /api/reload
POST /api/shutdown bearer token only
Expand Down Expand Up @@ -462,6 +499,9 @@ Its CLI:
| `lx open [id]` | Open the launcher, or a service's UI, in the browser with a session. |
| `lx logs <id> [-f]` | Show or follow captured output. |
| `lx add <path>` / `lx rm <id>` | Register or unregister a manifest. |
| `lx install [<source>]` | Install an app from a repository or folder, or with no source, list what is installed (§10.8). |
| `lx update [<name>…]` | Update installed apps, all of them by default; `--check` only reports. |
| `lx uninstall <name>` | Remove an installed app, keeping its data. |
| `lx check <id>` | Verify the service against its declared level. |
| `lx state` | Print the launcher's state document. |
| `lx agents` | List the services agents can discover (§10.7). |
Expand Down Expand Up @@ -494,6 +534,23 @@ Every published skill is a link from the agent's folder to `$LAUNCHX_HOME/agents

The switch decides what agents are told, not what they can reach. An agent runs as the user, so it can still read run files and call a service it was not told about (§11).

### 10.8 Installing, updating and removing apps

`lx install <source>` installs an app. The source is a git URL, `owner/repo` for a GitHub repository, or a folder on this machine.

- **A URL** is cloned into `$LAUNCHX_HOME/sources/<name>`, where the name is the repository's. LaunchX owns that checkout: it pulls it to update and deletes it on uninstall.
- **A folder** is installed where it is. LaunchX never pulls, changes or deletes it. This is how to install something that is not published, or a working copy.

LaunchX then reads the checkout's `launchx.toml`, shows its services, the installer command (§4.9) and where the app keeps data, and asks before going on (`--yes` skips the question). It checks `needs`, stops the app's running services, runs the installer, registers the app (§4.9), records it, and starts again what it stopped. Installing an app that is already installed updates it.

`lx update [<name>…]` pulls each cloned app with `git pull --ff-only` and, when there are new commits, runs its installer again (`--force` runs it anyway). An app installed from a folder is reinstalled from the folder as it is. Running services are stopped first and started again after. `lx update --check` fetches and reports without changing anything. The launcher also checks at start and every twelve hours, without pulling, and shows the apps that have updates.

`lx uninstall <name>` stops the app's services, runs its `uninstall` command, unregisters its manifests, deletes the checkout if LaunchX cloned it, and forgets it. The app's data stays, and the command says where. A service id works in place of the name.

`installs.json` records each app: its source, checkout, whether LaunchX cloned it, its services, the commit installed, its `data` paths, and when it was installed and updated.

The launcher's page does the same: an Install button takes a source and shows the plan before installing, and each installed app's card has Update and Uninstall. On the page each of these runs as a job whose output streams to the log panel. One install, update or uninstall runs at a time, from the page or the command line.

## 11. Security model

| Threat | Handled by |
Expand All @@ -507,6 +564,7 @@ The switch decides what agents are told, not what they can reach. An agent runs
| One service using memory under another's name | Memory tokens are per service and never handed to dependents; writes are logged under the caller's id, whatever it claims. |
| A lost update to a shared page | Every update names the revision it was based on; a stale one is refused (§12.5). |
| Other devices on the network | Everything binds to loopback by default. |
| Installing runs code from a repository | LaunchX installs only from a source the user names, shows the installer command and asks first. The page's install API needs the launcher session, like every other action. |

Out of scope: a hostile process running as the same user. It can read the run files, as it can read everything else the user owns. This includes an AI agent the user runs: hiding a service from agents (§10.7) keeps it out of what they are told, and a well-behaved agent stays away, but only running the agent as another user, or in a sandbox, keeps it out. The same holds for memory: its files are the user's, so a service that reads them directly, rather than through the API, is not stopped by the switch.

Expand Down Expand Up @@ -642,7 +700,8 @@ Commands that read take `--json`.

- **Action catalogue.** A machine-readable list of each service's actions, so one generic client (or one MCP server in the launcher) can drive every service. The likely next addition.
- **Remote and phone access.** Exposing the gateway on a LAN or Tailscale with pairing, so every service gets it at once.
- **Install and update.** `lx install <repo>`. For now, installing is the job of the service's own installer.
- **Restoring on a new machine.** `installs.json` lists every source, so `lx install` could reinstall them all from it.
- **Pinned versions.** `lx install` follows a repository's default branch; installing a tag or branch is not there yet.
- **Jobs.** One-shot or scheduled commands, as opposed to long-running services.
- **Adopting standalone instances.** A service started by hand is not taken over by the launcher.
- **Memory by page.** Access is per service, for all of memory. A switch per page or per group of pages (so a service could read `schedule` but not `resume`) is the likely next step.
Expand Down
38 changes: 38 additions & 0 deletions src/gateway.rs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ use serde_json::{Value, json};
use tokio::net::TcpListener;
use tokio::sync::{broadcast, watch};

use crate::jobs;
use crate::manifest;
use crate::memory::{self, Access, Who};
use crate::supervisor::{Event, Launcher};
Expand Down Expand Up @@ -303,6 +304,36 @@ impl App {
};
json_response(StatusCode::OK, json!({ "url": self.login_link(&self.launcher_host(), &landing) }))
}
(&Method::GET, ["api", "install", "log"]) => {
let lines = query(request.uri()).get("tail").and_then(|n| n.parse().ok()).unwrap_or(200usize).min(5000);
json_response(StatusCode::OK, json!({ "lines": jobs::log_tail(launcher, lines) }))
}
(&Method::POST, ["api", "install", "plan"]) => {
let body = read_json(request).await;
let Some(source) = body.get("source").and_then(Value::as_str).map(str::to_string) else {
return error(StatusCode::BAD_REQUEST, "Send {\"source\": \"<git URL, owner/repo or folder>\"}");
};
let name = body.get("name").and_then(Value::as_str).filter(|n| !n.is_empty()).map(str::to_string);
match jobs::plan(launcher, source, name).await {
Ok(plan) => json_response(StatusCode::OK, plan),
Err(message) => error(StatusCode::UNPROCESSABLE_ENTITY, &message),
}
}
(&Method::POST, ["api", "install"]) => {
let body = read_json(request).await;
let Some(source) = body.get("source").and_then(Value::as_str).map(str::to_string) else {
return error(StatusCode::BAD_REQUEST, "Send {\"source\": \"<git URL, owner/repo or folder>\"}");
};
let name = body.get("name").and_then(Value::as_str).filter(|n| !n.is_empty()).map(str::to_string);
job_response(jobs::start_install(launcher, source, name))
}
(&Method::POST, ["api", "packages", "check"]) => json_response(StatusCode::OK, jobs::check_updates(launcher).await),
(&Method::POST, ["api", "packages", name, "update"]) => {
let name = name.to_string();
let force = read_json(request).await.get("force").and_then(Value::as_bool).unwrap_or(false);
job_response(jobs::start_update(launcher, &name, force))
}
(&Method::POST, ["api", "packages", name, "uninstall"]) => job_response(jobs::start_uninstall(launcher, name)),
(&Method::POST, ["api", "reload"]) => json_response(StatusCode::OK, launcher.reload().await),
(&Method::POST, ["api", "shutdown"]) if bearer => {
let _ = self.shutdown.send(true);
Expand Down Expand Up @@ -609,6 +640,13 @@ async fn read_json_limit(request: Request, limit: usize) -> Value {
serde_json::from_slice(&body.to_bytes()).unwrap_or_else(|_| json!({}))
}

fn job_response(result: Result<jobs::Job, String>) -> Response {
match result {
Ok(job) => json_response(StatusCode::ACCEPTED, json!({ "job": job })),
Err(message) => error(StatusCode::CONFLICT, &message),
}
}

fn json_response(status: StatusCode, value: Value) -> Response {
Response::builder()
.status(status)
Expand Down
Loading