cogmoteGO is the "air traffic control" for remote neuroexperiments: a lightweight Go system coordinating distributed data streams, commands, and full experiment lifecycle management - from deployment to data collection.

• for matlab

curl -sS https://raw.githubusercontent.com/cagelab/cogmoteGO/main/install.sh | sh

irm -Uri 'https://raw.githubusercontent.com/cagelab/cogmoteGO/main/install.ps1' | iex

The winget version is relatively outdated; currently, we recommend installing via a script.

winget install ccccraz.cogmoteGO

restart the service as user

We recommend that you register cogmoteGO as a user service on Linux

cogmoteGO service -u

start the service as user

cogmoteGO service start -u

register the service

sudo cogmoteGO service

start the service

sudo cogmoteGO service start

register the service

note: you need to run the command as administrator

cogmoteGO service

start the service

cogmoteGO service start

restart the service as user

note: the password is required for running the service as user

cogmoteGO service -u -p <your_password>

start the service as user

cogmoteGO service start -u

for more info about the service, run

cogmoteGO service --help

curl --location --request GET 'http://localhost:9012/api/device'

cogmoteGO supports sending email notifications. Credentials are securely stored in the system keyring.

Interactive setup (prompts for email and password):

cogmoteGO email set

With SMTP server options:

cogmoteGO email set --host smtp.example.com --port 587

cogmoteGO email show

Example output:

Email Configuration:
  Email address : your@email.com
  SMTP host     : smtp.example.com
  SMTP port     : 587
  Recipients    : recipient1@example.com, recipient2@example.com
  Credentials   : configured

cogmoteGO email delete

cogmoteGO email --help

Manage application settings via CLI.

Show all configuration:

cogmoteGO config show

Show specific key:

cogmoteGO config show port

cogmoteGO config set port 8080
cogmoteGO config set proxy.max_retries 5

Reset specific key to default:

cogmoteGO config reset port

Reset all configuration (email settings not affected):

cogmoteGO config reset

cogmoteGO uses a separate listener for APIs that must only be available to programs running on the same host. The listener always binds to 127.0.0.1 and uses internal_port, which defaults to 9011. Changing the port does not expose the internal API to the network.

The public port and internal_port must be different. Configure the internal port and restart the service to apply the change:

cogmoteGO config set internal_port 9011

The backup endpoints are registered only on the internal listener. Local Python, MATLAB, and C# clients should therefore use http://127.0.0.1:<internal_port>/api/backups. Requests to /api/backups on the public port return 404 Not Found.

When cogmoteGO is behind Nginx or another reverse proxy, proxy only the public port. Do not proxy the internal port.

The backup API copies explicitly selected files or directories from trusted local roots to trusted mounted Samba roots. The API only accepts root IDs and relative paths, so callers cannot select arbitrary host filesystem paths.

Configure trusted roots before creating tasks:

cogmoteGO backup roots add source projectx-data /path/to/projectx/data
cogmoteGO backup roots add samba lab-nas /mnt/samba

List configured roots with cogmoteGO backup roots list. Restart the service after changing them.

The resulting configuration is:

{
  "backup": {
    "source_roots": [{"id": "projectx-data", "path": "/path/to/projectx/data"}],
    "samba_roots": [{"id": "lab-nas", "path": "/mnt/samba"}]
  }
}

Create an asynchronous backup task with Nushell:

http post http://127.0.0.1:9011/api/backups {
  source: {
    root_id: "projectx-data"
    entries: ["20260713" "20260714/realdata/result.jsonl"]
  }
  destination: {
    type: "samba"
    root_id: "lab-nas"
    path: "experiments/projectx/data"
  }
}

Each selected entry is mapped beneath the destination path. Existing destination entries cause the task to fail; entries are never overwritten or merged. Files are copied with SHA-256 verification. Only one backup task may run at a time; a concurrent request receives 409 Conflict. Failed transfers automatically remove .partial-<task-id> data. Tasks are kept only in memory, so a service restart requires the caller to submit the upload again. The service retains only the latest task; creating a new task replaces the previous completed task.

Poll GET /api/backups every 500 ms to 1 s. Before the first task is created, this endpoint returns 404 Not Found. The response includes status (running, succeeded, partially_succeeded, or failed) and phase (scanning, uploading, verifying, publishing, completed), files_total, files_completed, bytes_total, bytes_transferred, and current_path. Failed tasks retain the phase in which the failure occurred. Use bytes_transferred / bytes_total for the upload progress bar once the scanning phase completes.

cogmoteGO backup --help