Getting Started¶

cemi is designed around a local-first workflow:

Your training or benchmarking code writes run_record snapshots to disk with the Writer.
The local gateway reads those snapshots from the same directory.
The workspace UI loads metrics, parameters, and artifacts from that gateway.

Installation¶

Closed beta install: private GitHub Releases wheel¶

For the closed beta, distribute a prebuilt wheel through a private GitHub Release. Testers should download the wheel asset from the release page and install it locally:

pip install ./cemi-0.1.0-py3-none-any.whl

This is the preferred beta path because it installs the exact tested artifact without requiring a source checkout or frontend tooling.

From source¶

From the cemi repository root:

pip install -e ./cli

For test tooling:

pip install -e "./cli[dev]"

Canonical local flow¶

1. Create a writer in your script¶

from cemi.writer import create_writer

writer = create_writer(project="default", log_dir=".cemi")
writer.start_run(name="my-run")
writer.log_metric(name="loss", value=0.5, step=1)
writer.emit_run_record()

2. Start the local gateway¶

Use the same log_dir you passed to the Writer:

cemi gateway --save-dir .cemi

3. Open the workspace¶

cemi view

The local workspace is served at:

http://127.0.0.1:3141/workspace

Save directory contract¶

The Writer and gateway must agree on the same base directory.

<save_dir>/
  runs/
    <run_id>.jsonl
  artifacts/
    <run_id>/
      <filename>

The Writer emits run_record snapshots into runs/.
add_local_file_artifact() copies files into artifacts/<run_id>/.
The local gateway reads runs/*.jsonl and serves artifacts back to the workspace UI.

Closed beta scope¶

This beta is intentionally local-only.

cemi start, cemi view, cemi gateway, and cemi stop are the supported commands.
Run data stays on disk on the tester's machine.
The local gateway serves the embedded workspace and reads the same save directory as the Writer.
Cloud actions are hidden in the closed-beta build and are not part of tester setup.

Useful environment variables¶

CEMI_SAVE_DIR: base directory for runs/ and artifacts/
CEMI_LOCAL_DIR: override just the runs directory
CEMI_ARTIFACTS_DIR: override just the artifacts directory
CEMI_LOCAL_SERVER_URL: gateway base URL, useful when serving on a custom port
CEMI_SINK: local sink mode such as local or local+local_server

Local data and operations¶

What gets written to disk¶

Run snapshots are appended to save_dir/runs/<run_id>.jsonl.
Copied artifacts are stored under save_dir/artifacts/<run_id>/.
Local CLI config is stored under ~/.cemi/config.json.
PID files used by cemi stop are stored under ~/.cemi/pids/.

Default locations¶

Project-local data defaults to .cemi/ in the current working directory.
Per-user CLI state lives under ~/.cemi/.

Artifact sensitivity¶

Artifacts may include model binaries, checkpoints, evaluation reports, or copied local files. Treat add_local_file_artifact() as copying that file into CEMI's artifact store for local serving. Do not attach secrets, credentials, private datasets, or files you would not want duplicated locally.

Gateway bind policy¶

For the closed beta, the gateway should remain bound to 127.0.0.1 only. It is meant to be used locally on the same machine, not as a shared service.

Browser behavior¶

cemi view opens the browser automatically after the gateway starts.
cemi start opens the browser automatically before it launches your command.
cemi gateway does not open the browser automatically.

Stop background processes¶

cemi stop

Use this after cemi start --dev-ui or cemi view --dev-ui.

Clear old state¶

Project-local state:

rm -rf .cemi

Per-user state:

rm -rf ~/.cemi

Only do this if you no longer need the saved runs, artifacts, config, or PID files.

Reset a broken local setup¶

Run cemi stop.
Remove stale project state with rm -rf .cemi if needed.
Remove stale user state with rm -rf ~/.cemi if needed.
Reinstall the published wheel from the private GitHub Release.

Uninstall¶

pip uninstall cemi

If you also want to remove saved state, delete .cemi in your project directory and ~/.cemi in your home directory.

Troubleshooting¶

No runs show up in the UI¶

Make sure the Writer log_dir and gateway --save-dir are the same path.

Artifact URLs 404¶

If the gateway is not running on port 3141, set CEMI_LOCAL_SERVER_URL before creating artifacts so the generated URLs match the active gateway.

I already have a job writing runs¶

Start the gateway later with the same save directory and open the workspace:

cemi gateway --save-dir /path/to/log_dir
cemi view