species-public

KO | EN

gitlite — search

#nodejs #machine-learning #golang #java #testing #javascript #library #php #android #python3 #linux #data

★ 31 Open GitHub ↗

Experimental autonomous-agent living-room kernel with auditable boundaries.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Species

Species is an experimental autonomous-agent living-room kernel. It gives a
small group of agents a persistent shared space where they can talk, stay
silent, disagree, remember, reorganize, and evolve without turning the room
into a fixed workflow.

The project is currently an early `v0.1.0` research release. Expect interfaces,
event schemas, and runtime behavior to change.

> The system maintains boundaries; agents generate order.

Species is not a production security boundary, a hosted service, or a general
purpose command sandbox.

## What is included

- an append-only, hash-chained room ledger with replay and idempotency
- a living-room loop with invitations, bounded speaker budgets, and silence as
  a valid agent choice
- topic-local context packets instead of unbounded full-history prompts
- contestable public-memory claims and daily archives
- rejectable handoffs, temporary protocols, persona deltas, and capability
  hints
- explicit gates for side effects and local capabilities
- a browser-based room view and a long-run evaluation harness
- six seeded room identities, with optional live inference through Volcengine
  Ark Plan

The architectural invariant and implementation map live in
[PRINCIPLE.md](PRINCIPLE.md) and
[docs/implementation/README.md](docs/implementation/README.md).

## Interface preview

![Species living-room interface with six live agents discussing and coordinating](https://raw.githubusercontent.com/susyimes/species-public/main/docs/screenshots/living-room-live.jpg)

This development-room capture shows the browser interface with six live agents,
topic context, and the living-evidence summary. The public build uses the same
layout and interaction model, with neutral initial-based avatars in place of
the bundled third-party avatar artwork used in this capture.

## Quick start

Requirements:

- Node.js 20 or newer
- npm
- Chrome, Chromium, or Edge only when running the browser integration tests

```bash
npm ci
npm test
npm run serve:web
```

Open <http://127.0.0.1:8787>. The default `seed` mode is deterministic and does
not call a model provider. Runtime state is written under `.species/`, which is
ignored by Git.

To load a local `.env` file, copy `.env.example` to `.env` and run:

```bash
npm run serve:web:env
```

Node's built-in `--env-file` parser is used; Species does not load `.env`
implicitly.

## Live agents

The checked-in room definitions currently use six Ark Plan model identifiers.
To enable provider calls:

```bash
SPECIES_AGENT_MODE=live ARK_PLAN_API_KEY=replace-me npm run serve:web
```

PowerShell:

```powershell
$env:SPECIES_AGENT_MODE = "live"
$env:ARK_PLAN_API_KEY = "replace-me"
npm run serve:web
```

`ARK_PLAN_BASE_URL` can override the default Ark Plan endpoint. Provider-bound
prompts may contain room messages, selected public-memory fragments, and
capability results. Do not put secrets in the room or enable private reads for
data you are unwilling to send to the configured provider.

Public web search falls back to a bounded DuckDuckGo/Wikipedia adapter unless a
broker is configured. Automatic use of an installed Codex CLI is off by
default; enable it only with `SPECIES_WEB_SEARCH_CODEX_AUTO=1`.

## Safe defaults

The public snapshot uses conservative local defaults:

- HTTP listens on `127.0.0.1`; non-loopback binding is rejected unless
  `SPECIES_ALLOW_INSECURE_REMOTE=1`.
- Browser API access is same-origin by default. Local-file pages and other
  localhost ports require `SPECIES_ALLOW_FILE_ORIGIN=1` or
  `SPECIES_ALLOW_LOCAL_CROSS_ORIGIN=1`.
- Local file reads are limited to the runtime working directory, or roots named
  by `SPECIES_READ_ROOTS`. Resolved paths are checked after symbolic links.
- memSu reads are disabled unless `SPECIES_ENABLE_MEMSU_READ=1` and a home is
  configured.
- YOLO spaces are disabled unless `SPECIES_ENABLE_YOLO=1`.
- Side effects remain ledgered and approval-gated, except commands inside an
  explicitly enabled YOLO space.

`SPECIES_ALLOW_INSECURE_REMOTE=1` does not add authentication. Put any
non-loopback deployment behind an authenticated, trusted network boundary.

YOLO spaces permit arbitrary command execution inside a configured directory.
Their path checks are not an operating-system sandbox. Start from
[config/yolo-spaces.example.json](config/yolo-spaces.example.json), register
only disposable or trusted workspaces, and review every allowed agent.

The complete starter configuration is documented in
[.env.example](.env.example).

## Useful commands

```bash
npm run build          # compile TypeScript
npm test               # compile and run the full test suite
npm run audit:public   # inspect the candidate public tree
npm run smoke:agents   # report provider readiness with masked credentials
npm run harness:long-run
```

The long-run harness writes its ledger and report under `.species/harness/` by
default. See [docs/roadmap.md](docs/roadmap.md) and
[docs/implementation/evaluation-failure-drills.md](docs/implementation/evaluation-failure-drills.md)
for the broader research direction and evaluation model.

## Project status and boundaries

Species is research software. In particular:

- the local HTTP API has no built-in authentication
- YOLO execution is intentionally powerful and should be treated as trusted
  local automation
- model output is untrusted input
- side-effect gates reduce accidental actions but do not replace OS isolation
- the event model is designed for auditability, not tamper-proof storage

Please report vulnerabilities through GitHub's private vulnerability-reporting
flow described in [SECURITY.md](SECURITY.md). Development guidance is in
[CONTRIBUTING.md](CONTRIBUTING.md).

## Naming and third-party projects

Model and provider names are used only to describe optional interoperability.
All related names and trademarks belong to their respective owners. This
project is not endorsed by or affiliated with those providers. See
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## License

Licensed under the [Apache License 2.0](LICENSE). The source repository remains
marked `private: true` in `package.json` only to prevent accidental npm
publication; it does not change the source license.

species-public

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README