Files
bytebot/docs/quickstart.mdx
2025-07-02 16:43:46 -04:00

260 lines
6.9 KiB
Plaintext

---
title: "Quick Start"
description: "Get your AI desktop agent running in 2 minutes"
---
# Host Bytebot on Railway
## ☁️ One-click Deploy on Railway
[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/bytebot?referralCode=L9lKXQ)
<Steps>
<Step title="Visit the Template">
Click the Deploy Now button in the Bytebot template on Railway.
</Step>
<Step title="Add Anthropic Key">
Enter your `ANTHROPIC_API_KEY` as the single required environment variable.
</Step>
<Step title="Deploy &amp; Launch">
Hit **Deploy**. Railway will build the stack, wire the services together via private networking and output a public URL for the UI. Your agent should be ready within a couple of minutes!
</Step>
</Steps>
<Note>
Need more details? See the full <a href="/deployment/railway">Railway deployment guide</a>.
</Note>
---
# Self-host Bytebot
## Prerequisites
- Docker ≥ 20.10
- Docker Compose
- 4GB+ RAM available
- Anthropic API key ([get one here](https://console.anthropic.com))
## 🚀 2-Minute Setup
Get your self-hosted AI desktop agent running with just three commands:
<Steps>
<Step title="Clone and Configure">
```bash
git clone https://github.com/bytebot-ai/bytebot.git cd bytebot echo "ANTHROPIC_API_KEY=your_api_key_here" > docker/.env
```
</Step>
<Step title="Start the Agent Stack">
```bash
docker-compose -f docker/docker-compose.yml up -d
```
This starts all four services:
- **Bytebot Desktop**: Containerized Linux environment
- **AI Agent**: Claude-powered task processor
- **Chat UI**: Web interface for interaction
- **Database**: PostgreSQL for persistence
</Step>
<Step title="Open the Chat Interface">
Navigate to [http://localhost:9992](http://localhost:9992) and start chatting!
Try asking:
- "Open Firefox and search for the weather forecast"
- "Take a screenshot of the desktop"
- "Create a text file with today's date"
</Step>
</Steps>
<Note>
**First time?** The initial startup may take 2-3 minutes as Docker downloads
the images. Subsequent starts will be much faster.
</Note>
## What Just Happened?
You now have a fully functional AI agent that can:
- 🖱️ Control mouse and keyboard
- 🌐 Browse the web
- 📄 Create and edit documents
- 📧 Manage emails
- 🔄 Automate any desktop task
Watch it work in real-time through the embedded VNC viewer in the tasks interface!
## Try These Example Tasks
<CardGroup cols={2}>
<Card title="Web Research" icon="magnifying-glass">
"Find the top 5 news stories about AI today and summarize them"
</Card>
<Card title="Data Collection" icon="table">
"Go to example.com and extract all email addresses into a list"
</Card>
<Card title="File Management" icon="folder">
"Create a folder called 'reports' and organize files by date"
</Card>
<Card title="Testing" icon="vial">
"Test the login flow on our staging site"
</Card>
</CardGroup>
## Accessing Your Services
| Service | URL | Purpose |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| **Tasks UI** | [http://localhost:9992](http://localhost:9992) | Main interface for interacting with the agent |
| **Agent API** | [http://localhost:9991/tasks](http://localhost:9991/tasks) | REST API for programmatic task creation |
| **Computer API** | [http://localhost:9990/computer-use](http://localhost:9990/computer-use) | Low-level desktop control API |
| **MCP SSE** | [http://localhost:9990/sse](http://localhost:9990/sse) | Connect MCP clients for tool access |
## Alternative Deployment Options
<Tabs>
<Tab title="Desktop Container Only">
If you just want the containerized desktop without the AI agent:
```bash
#Using pre-built image (recommended)
docker-compose -f docker/docker-compose.core.yml pull
docker-compose -f docker/docker-compose.core.yml up -d
```
Or build locally:
```bash
docker-compose -f docker/docker-compose.core.yml up -d --build
```
Access the desktop at
[http://localhost:9990/vnc](http://localhost:9990/vnc)
</Tab>
</Tabs>
## Managing Your Agent
### View Logs
Monitor what your agent is doing:
```bash
# All services
docker-compose -f docker/docker-compose.yml logs -f
# Just the agent
docker-compose -f docker/docker-compose.yml logs -f bytebot-agent
```
### Stop Services
```bash
docker-compose -f docker/docker-compose.yml down
```
### Update to Latest
```bash
docker-compose -f docker/docker-compose.yml pull
docker-compose -f docker/docker-compose.yml up -d
```
### Reset Everything
Remove all data and start fresh:
```bash
docker-compose -f docker/docker-compose.yml down -v
```
## Quick API Examples
### Create a Task via API
```bash
curl -X POST http://localhost:9991/tasks \
-H "Content-Type: application/json" \
-d '{
"description": "Search for flights from NYC to London next month",
"type": "browser_task"
}'
```
### Direct Desktop Control
```bash
# Take a screenshot
curl -X POST http://localhost:9990/api/computer \
-H "Content-Type: application/json" \
-d '{"action": "screenshot"}'
# Type text
curl -X POST http://localhost:9990/api/computer \
-H "Content-Type: application/json" \
-d '{"action": "type_text", "text": "Hello, Bytebot!"}'
```
## Troubleshooting
<AccordionGroup>
<Accordion title="Container won't start">
Check Docker is running and you have enough resources:
```bash
docker info
docker-compose -f docker/docker-compose.yml logs
```
</Accordion>
<Accordion title="Can't connect to tasks UI">
Ensure all services are running:
```bash
docker-compose -f docker/docker-compose.yml ps
```
All services should show as "Up".
</Accordion>
<Accordion title="Agent errors or no response">
Check your API key is set correctly:
```bash
cat docker/.env
docker-compose -f docker/docker-compose.yml logs bytebot-agent
```
</Accordion>
</AccordionGroup>
## Next Steps
<CardGroup cols={2}>
<Card
title="Architecture Overview"
icon="sitemap"
href="/core-concepts/architecture"
>
Understand how all the components work together
</Card>
<Card title="Agent System" icon="robot" href="/core-concepts/agent-system">
Deep dive into the AI agent capabilities
</Card>
<Card title="API Reference" icon="code" href="/api-reference/introduction">
Build integrations with the REST APIs
</Card>
<Card
title="Use Cases"
icon="lightbulb"
href="/core-concepts/agent-system#use-cases"
>
Explore what others are building
</Card>
</CardGroup>
<Note>
**Need help?** Join our [Discord
community](https://discord.com/invite/zcb5wA2t4u) for support and to share
what you're building!
</Note>