https://github.com/z4jdev/z4j-bare
z4j framework-free agent bootstrapper (Apache 2.0)
https://github.com/z4jdev/z4j-bare
agent apache-2-0 bare python task-queue z4j
Last synced: 12 days ago
JSON representation
z4j framework-free agent bootstrapper (Apache 2.0)
- Host: GitHub
- URL: https://github.com/z4jdev/z4j-bare
- Owner: z4jdev
- License: apache-2.0
- Created: 2026-04-22T16:12:17.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-30T18:41:02.000Z (28 days ago)
- Last Synced: 2026-04-30T20:16:51.724Z (28 days ago)
- Topics: agent, apache-2-0, bare, python, task-queue, z4j
- Language: Python
- Homepage: https://pypi.org/project/z4j-bare/
- Size: 261 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# z4j-bare
[](https://pypi.org/project/z4j-bare/)
[](https://pypi.org/project/z4j-bare/)
[](https://github.com/z4jdev/z4j-bare/blob/main/LICENSE)
The framework-free agent runtime for [z4j](https://z4j.com).
Bootstraps a z4j agent inside any Python process, Celery worker,
RQ worker, Dramatiq actor, plain script, custom service, and connects
it to z4j over an authenticated WebSocket. Used directly when
there's no framework adapter (z4j-django / z4j-flask / z4j-fastapi);
used indirectly by those framework adapters too.
## What it ships
- **Agent runtime**, connect, authenticate, supervise, reconnect
with bounded backoff
- **Outbound buffer**, every event written to a local SQLite ring
before going out on the wire; durable across short brain outages
and agent restarts
- **Engine signal hooks**, wired up by whichever engine adapter you
install (z4j-celery, z4j-rq, etc.); the runtime drains them into
the buffer
- **Schedule inventory**, emits a full snapshot at boot, on a
periodic timer (default 15 min), and on demand from the brain's
*Sync now* command. Existing schedules show up automatically.
- **Command dispatcher**, receives operator actions from the brain
(retry, cancel, restart, schedule.fire, schedule.resync, etc.)
and routes them to the right adapter
## Install
```bash
pip install z4j-bare
```
Most users install a framework adapter (z4j-django / z4j-flask /
z4j-fastapi) which pulls z4j-bare automatically.
## Quick start (framework-free worker)
```python
from z4j_bare import install_agent
from z4j_celery import CeleryEngineAdapter
install_agent(
engines=[CeleryEngineAdapter(celery_app=app)],
brain_url="https://brain.example.com",
token="z4j_agent_...",
project_id="my-project",
)
```
## Reliability
- No exception from the agent ever propagates back into your worker /
signal handler / request path. Every brain interaction is wrapped in
a top-level try/except.
- Events buffer locally when z4j is unreachable. Workers never
block on network I/O.
- Supervisor reconnects on every transient failure (network, TLS,
protocol mismatch) with bounded backoff.
## Documentation
Full docs at [z4j.dev/frameworks/bare/](https://z4j.dev/frameworks/bare/).
## License
Apache-2.0, see [LICENSE](LICENSE).
## Links
- Homepage: https://z4j.com
- Documentation: https://z4j.dev
- PyPI: https://pypi.org/project/z4j-bare/
- Issues: https://github.com/z4jdev/z4j-bare/issues
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Security: security@z4j.com (see [SECURITY.md](SECURITY.md))