@osaas/service-builder
v0.19.1
Published
Run your own OSC Service Builder Agent and contribute to the Open Source Cloud community
Readme
osaas-service-builder
🤖 Run your own OSC Service Builder Agent and contribute to the Open Source Cloud community!
This tool automatically containerizes GitHub repositories using AI and contributes them to the Open Source Cloud (OSC) ecosystem. By running an agent, you help expand the catalog of one-click deployable open source services.
🚀 Quick Start: Run Your Own Agent
Want to contribute computing power to the OSC community? Start here!
1. Prerequisites
Make sure you have:
- Docker: Install Docker and ensure it's running
- The agent builds and tests containers, so Docker is required
- GitHub Organization Access: Your GitHub user needs to be granted access to the
eyevinn-osaasorganization- Apply for access by emailing [email protected]
2. Get Your Credentials
You need three things:
- OSC Access Token: Get it from osaas.io (sign up → profile → generate token)
- GitHub Token: GitHub Settings → Personal access tokens → Generate (needs
reposcope) - Claude API Key: Anthropic Console → Create API key
3. Run Your Agent (No Installation Required!)
# Set your credentials
export OSC_ACCESS_TOKEN=your-osc-access-token
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export CLAUDE_API_KEY=sk-ant-xxxxxxxxxxxx
# Start contributing to OSC!
npx -y @osaas/service-builder agentThat's it! Your agent is now helping containerize open source projects for the OSC community. 🎉
Alternative: Custom Configuration
npx -y @osaas/service-builder agent \
--api-key=your-osc-access-token \
--token=ghp_xxxxxxxxxxxx \
--claude-key=sk-ant-xxxxxxxxxxxx \
--agent-id=my-builder-agent🌟 What Your Agent Does
Your agent automatically:
- ✅ Polls the OSC queue for containerization jobs
- ✅ Analyzes GitHub repositories using AI to understand project structure
- ✅ Generates optimized Dockerfiles for different project types (Node.js, Python, Go, etc.)
- ✅ Creates forks and pushes Docker configurations
- ✅ Submits services to the OSC marketplace for one-click deployment
- ✅ Makes open source more accessible by removing deployment barriers
🏆 Contributing to OSC
By running an agent, you're helping to:
- Expand the OSC Catalog: More containerized services available to everyone
- Democratize Infrastructure: Help smaller projects get proper containerization
- Build the Future of Open Source: Create a decentralized network of deployable services
- Earn Recognition: Get community badges and potential collaboration opportunities
📊 Monitor Your Agent
Your agent provides real-time feedback:
# Run with debug output to see what's happening
DEBUG=osaas:* npx -y @osaas/service-builder agent
# Your agent will show:
# - Jobs picked up from the queue
# - Repository analysis progress
# - Dockerfile generation status
# - Successful submissions to OSC⚡ One-Time Containerization
Want to containerize a single repository? Use the direct mode:
npx -y @osaas/service-builder https://github.com/username/project \
--token=ghp_xxxxxxxxxxxx \
--claude-key=sk-ant-xxxxxxxxxxxxThis analyzes the repository, generates a Dockerfile, and optionally submits it to OSC.
🔧 Advanced Usage
For detailed CLI options, development setup, API integration, and advanced agent configurations, see ADVANCED.md.
Key advanced topics covered:
- Running multiple agents
- Production deployment with PM2/Docker
- Detailed logging and debugging
- Fork sync operations
- Environment variable detection
- Maker service integration
📌 Promote :latest to :stable (promote-stable)
promote-stable is the Job-side subcommand that moves the :stable tag of one or more images on GHCR, as a registry-side manifest copy (docker buildx imagetools create, no rebuild and no layer pull). It reads no GitHub credential: the only credential is the GHCR token (GHCR_TOKEN_FILE, then GHCR_TOKEN), which needs write:packages on the fork org. There is no dry-run mode.
osc-builder promote-stable <image...> [--env <env>] [--source-digest <image=digest>]... [--pin-digest <digest>]<image...>: repository names as osaas-maker pushes them, without registry or org. Each becomesghcr.io/<fork org>/<name>; the fork org derives from--env(defaultENVIRONMENT, thenprod).--source-digest <image=sha256:...>(repeatable): promote this digest for that image instead of its current:latest(the rollback case). The digest must exist in the repository.--pin-digest <sha256:...>: must equal the current:latestof one image that has no--source-digest; that image is pinned to it and the others resolve their current:latest. A digest that matches no image fails withunknown_source_digest.
Phases: (1) resolve, reads only: every :latest (or explicit digest) and the current :stable (absent is allowed) are read and pinned by digest, and all sources are verified before anything is written; (2) retag, per image: the old stable digest is first copied to the tag stable-previous (one moving tag, so only the newest previous stable stays addressable and an older rollback digest may have been pruned by GHCR, see agent-team-osc-dev#224, which then ends unknown_source_digest with nothing moved), then the source is copied to :stable; (3) verify: :stable is read back and compared with the recorded source digest. On a retag or verification failure the images already moved are restored to their previous digests. A first-ever :stable cannot be deleted by imagetools, so such an image is reported restore_failed.
The result record is the pod termination message (/dev/termination-log, compact JSON, well below the 4096-byte limit for four images). Exit code 0 on DONE, 1 on FAILED.
{
"outcome": "DONE",
"images": [
{
"name": "web-runner",
"sourceTag": "latest",
"sourceDigest": "sha256:...",
"previousStableDigest": "sha256:... or null",
"newStableDigest": "sha256:...",
"state": "promoted"
}
]
}sourceTag is latest or digest; state is promoted, restored, untouched or restore_failed. On failure outcome is FAILED and reason and message are set (the shape getSyncForkJobStatus already parses). Reasons: missing_latest, unknown_source_digest, registry_auth_failure, retag_failure, verification_failure, invalid_input.
🤝 Community & Support
- Slack: http://slack.osaas.io/ - Ask questions and get help
- Documentation: https://docs.osaas.io - Full OSC documentation
- Issues: GitHub Issues - Report bugs
- Discussions: GitHub Discussions - Feature requests
🎯 Recognition & Rewards
Active agent operators may receive:
- 🏅 Community recognition and badges
- 🚀 Early access to new OSC features
- 💼 Direct collaboration opportunities with Eyevinn Technology
- 💰 Potential revenue sharing as the ecosystem grows
About Eyevinn Technology
Eyevinn Technology is an independent consulting company that helps businesses in the video industry to optimize and streamline their operations. We are not commercially tied to any platform or technology vendor. As our way to innovate and push the industry forward, we develop proof-of-concepts and tools. Things we learn and develop we share as open-source.
With Eyevinn Open Source Cloud (OSC), we enable companies to build video solutions based on Open Source and avoid vendor lock-in. Our open-source solutions offer full flexibility with a revenue share model that supports the creators.
Contact [email protected] if you are interested in our consulting services.
