> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Faq

# FAQ

Common questions about Maestro and how it works.

## What Is Maestro?

### What exactly is Maestro?

Maestro is a conversational AI Engineer that delivers from deep research to validated, production-ready code. It goes beyond code generation to handle planning, implementation, testing, documentation, and delivery of complete features and systems.

Think of Maestro as an engineering teammate, not a coding tool.

### How is Maestro different from GitHub Copilot or Cursor?

| Feature        | Copilot/Cursor                    | Maestro                                |
| -------------- | --------------------------------- | -------------------------------------- |
| **Scope**      | Code suggestions and autocomplete | Complete feature implementation        |
| **Validation** | You test the code                 | Maestro tests its own code             |
| **Planning**   | You plan the implementation       | Maestro plans with you                 |
| **Testing**    | You write and run tests           | Maestro writes and runs tests          |
| **Delivery**   | Code snippets                     | Production-ready features              |
| **Context**    | Current file + nearby files       | Entire project, full iteration history |

**Summary**: Copilot/Cursor are coding assistants. Maestro is an engineering partner.

### Is Maestro a chatbot that writes code?

No. Maestro is a **system** that orchestrates multiple specialized models, execution environments, and validation tools to deliver complete solutions.

**Architecture**:

* Multiple LLMs, each optimized for specific tasks (research, coding, verification, optimization)
* Secure sandboxes for testing and validation
* Rich toolbox for file management, web research, visualization
* Quality oversight and validation layers

**You interact** through conversation, but Maestro is executing complex orchestration underneath.

### Can non-developers use Maestro?

Maestro is designed for technical professionals who understand:

* Software requirements and architecture
* Testing and validation concepts
* Code quality and performance

**Minimum technical literacy**:

* Understand what good code looks like
* Recognize test failures
* Evaluate performance metrics
* Make technical trade-off decisions

**If you're not technical**: Maestro may be overwhelming. It's optimized for engineering professionals who know what they want but need help executing.

## How Maestro Works

### How does Maestro actually work?

**Orchestration layer** coordinates:

1. **Research models**: Gather information, analyze approaches
2. **Planning models**: Design systems, create specifications
3. **Implementation models**: Write code, refactor, optimize
4. **Validation models**: Review code, flag issues, ensure quality

**Execution environment**:

* Isolated Ubuntu Linux sandboxes
* Real code execution and testing
* Performance benchmarking
* Validation of claims

**Toolbox**:

* File management and analysis
* Terminal access and execution
* Web research and browsing
* Visualization and diagramming
* External service integration

**You collaborate** by setting goals, reviewing proposals, validating outcomes, and maintaining quality standards.

### Do I need to write any code?

No. Your role shifts from writing syntax to:

* Defining goals and constraints
* Making architectural decisions
* Reviewing and validating implementations
* Ensuring quality standards
* Providing domain expertise

**You guide, Maestro implements.**

However, you should understand code well enough to:

* Review Maestro's implementations
* Spot logical errors
* Validate test coverage
* Make informed technical decisions

### Does Maestro make mistakes?

Yes. Maestro is powerful but not infallible:

* Can misunderstand requirements
* May choose suboptimal approaches
* Sometimes needs multiple attempts
* Occasionally makes logical errors

**Your job**: Catch mistakes, provide correction, demand higher quality.

**Built-in safeguards**:

* Systematic testing
* Multi-model validation
* Quality oversight
* Your review

**Best practice**: Treat Maestro's output skeptically until proven with tests and validation.

### Can Maestro learn from my feedback?

**Within a session**: Yes

* Maestro incorporates feedback immediately
* Adjusts approach based on corrections
* Learns your preferences and patterns
* Improves throughout the session

**Across sessions**: Limited

* General knowledge doesn't transfer between sessions
* Each session starts fresh
* But you can provide context via custom instructions

**Your project patterns**: Can be encoded as custom instructions that apply across sessions.

## Use Cases and Capabilities

### What kinds of projects can Maestro complete?

**Software development**:

* REST APIs and web services
* Full-stack applications
* Database schemas and migrations
* Authentication and authorization systems
* Caching layers and performance optimization
* Integration with third-party APIs

**Data engineering**:

* ETL pipelines
* Data transformation logic
* Quality validation systems
* Data analysis workflows

**Machine learning**:

* Model training pipelines
* Feature engineering
* Inference services
* ML model optimization

**DevOps and infrastructure**:

* CI/CD pipeline configuration
* Deployment automation
* Infrastructure as Code
* Monitoring and alerting

**Analysis and research**:

* Competitive technical analysis
* Performance benchmarking
* Root cause investigation
* Technology evaluation

**Limitations**: Maestro works best on projects that can be validated in sandboxes. Projects requiring specialized hardware, proprietary systems, or external dependencies may be challenging.

### Can I use Maestro with my existing codebase?

Yes. Maestro supports:

* **GitHub integration**: Clone any repository (public or private)
* **Direct upload**: Zip or tar your codebase, Maestro extracts it
* **Gradual integration**: Start with analysis, then implement changes

**Best results** with:

* Well-tested codebases (Maestro preserves test behavior)
* Clear documentation (helps Maestro understand)
* Consistent patterns (easier to follow and extend)

**Challenges** with:

* Poorly documented legacy code
* No tests (hard to validate changes)
* Highly coupled architecture
* Unusual or proprietary frameworks

**Recommendation**: Even challenging codebases benefit, but expect more iteration and validation.

### What if my codebase is too large for Maestro?

**Current limit**: Repositories up to \~10GB

**For larger codebases**:

* **Clone subsets**: Work on specific modules/services
* **Parallel sessions**: Different parts in different sessions
* **Strategic cloning**: Clone only what's needed for current work

**Future**: Support for larger repositories is planned.

### Can Maestro work with multiple repositories?

Yes. Common patterns:

**Microservices**:

```
Clone all relevant service repositories
Implement changes across services
Create coordinated PRs
Link PRs for review coordination
```

**Monorepo subsystems**:

```
Clone monorepo once
Work on different subsystems
File management keeps work organized
```

**Frontend + Backend**:

```
Clone both repositories
Coordinate API changes
Implement frontend consuming new API
Create PRs for both with cross-references
```

## Integration and Tooling

### What tools and integrations are supported?

**Source control**:

* GitHub (native integration)
* GitLab (API access)
* Bitbucket (git operations)

**Cloud providers**:

* AWS (S3, EC2, Lambda, etc.)
* Azure (Blob Storage, VMs, etc.)
* GCP (Cloud Storage, Compute Engine, etc.)

**Databases**:

* PostgreSQL, MySQL, SQLite
* MongoDB, Redis, Memcached
* Any database accessible via connection string

**APIs and services**:

* OpenAI, Anthropic (AI APIs)
* Stripe (payments)
* SendGrid, Mailgun (email)
* Custom REST/GraphQL APIs

**Development tools**:

* Package managers (pip, npm, cargo, go get)
* Test frameworks (pytest, jest, go test, etc.)
* Build tools (webpack, vite, cargo, maven)
* CI/CD (GitHub Actions compatible)

**Browsers and web**:

* Automated browser control
* Screenshot capture
* Web scraping
* Public URL access

### Can I integrate Maestro with Slack/Discord/Teams?

**Notifications**: Yes, push notifications can integrate with messaging platforms.

**Chat integration**: Multi-channel support is possible, but direct Slack/Discord bots require configuration beyond standard Maestro.

**Workaround**: Use Maestro via web interface, share results in chat.

### Can Maestro access private resources?

Yes, with proper credential setup:

* **Private GitHub repos**: OAuth authentication
* **Private APIs**: API keys via credential manager
* **Internal databases**: Connection strings (ensure network access)
* **VPNs**: SSH sandboxes can connect through jump hosts

**Security**: All credentials user-controlled, session-scoped, never logged.

## Security and Privacy

### Is Maestro secure?

Yes. Enterprise-grade security model:

**Isolation**:

* Dedicated sandbox per session
* Process isolation between users
* Credential isolation per session

**Credentials**:

* Encrypted at rest
* User-controlled activation
* Never logged or shared
* Automatic cleanup

**Code execution**:

* Sandboxed Firecracker microVMs
* No access to host system
* Limited resource quotas
* Network isolation options

**Data handling**:

* Your code never used for training
* Sessions completely isolated
* Optional data persistence (you control)

### Does Maestro learn from my code?

**No**. Maestro does not train on user data.

**What persists**:

* Your session state (if you choose to save it)
* Files you create (in your session only)
* Clone records (for your sessions only)

**What doesn't persist across sessions/users**:

* Code patterns you use
* Architectural choices
* Domain knowledge
* Anything from your work

**Privacy guarantee**: Your data is private. Each session is isolated.

### Can other users see my code?

**No.** Complete isolation:

* Sessions are private to your account
* Other users cannot access your sessions
* Other users cannot see your files
* Other users cannot view your history

**Collaboration**: Explicitly share session access if needed (enterprise features).

### What happens to my data if I cancel my subscription?

**Depends on data persistence settings**:

* **Checkpointed sessions**: Preserved per retention policy (typically 30-90 days)
* **Deleted sessions**: Immediate removal on request
* **Exported files**: You keep what you downloaded

**Best practice**: Use `/download-all` before cancelling to preserve your work.

## Billing and Plans

### How much does Maestro cost?

**Pricing model**: Monthly subscription with credit-based usage

**Plan tiers** (example structure):

* **Basic**: \$X/month + Y credits
* **Pro**: \$X/month + Y credits
* **Ultimate**: \$X/month + Y credits

**Credits** cover:

* Model API calls (passed through at cost, no markup)
* Sandbox compute time
* Storage (files and checkpoints)

**Visit**: [https://igent.ai/](https://igent.ai/) for current pricing

### How do credits work?

**Credit consumption**:

* Different models cost different amounts
* Longer responses cost more (more tokens)
* Sandbox execution time counted
* Storage and bandwidth included up to limits

**Credit management**:

* Track balance in UI
* Low balance warnings
* `/topup` command for quick refill
* Optional auto-reload (configure in settings)

**No surprises**:

* Real-time credit usage shown
* Warnings before large operations
* Control credit consumption via session management

### Do I need my own OpenAI/Anthropic accounts?

**No**. Maestro handles all model calls:

* We manage API accounts
* We orchestrate model calls
* We pass through costs to your credits
* **No markup**: You pay model cost + platform fee

**Advantage**: No need to manage multiple API accounts, rate limits, or billing.

### Can I control costs?

Yes, several ways:

**Session management**:

* Shorter sessions cost less
* `/compact` and `/forget` reduce ongoing costs
* `/refresh` reduces token usage per turn

**Tool selection**:

* Disable expensive tools if not needed
* Use faster tools when appropriate (Google vs Perplexity)
* Limit sandbox usage for non-execution tasks

**Model selection** (if configurable):

* Use cheaper models for simple tasks
* Use premium models for complex reasoning

**Auto-reload threshold**:

* Set maximum auto-reload amount
* Prevent runaway costs
* Manual approval for large expenses

## Session and State

### How long can sessions run?

**Technically**: Days to weeks

* Sessions checkpoint automatically
* Resumable across long periods
* Context preserved

**Practically**: Most sessions complete in hours

* Complex projects: Multiple focused sessions better than one massive session
* Capacity management: Easier with bounded sessions
* Checkpointing: Natural session boundaries

**Record**: Some users have single sessions spanning 100+ turns over multiple days.

### Can I have multiple sessions?

Yes. **Parallel sessions** are common:

**Use cases**:

* Different features in parallel
* Separate concerns (frontend vs backend)
* Experimental vs production work
* Personal vs work projects

**Isolation**: Sessions are completely independent.

### What happens if my browser crashes?

**Session state preserved**:

* Automatic checkpointing saves state
* Refresh browser to reload session
* Complete history restored
* Work continues from where you left off

**Sandbox state**:

* Running processes continue
* Files preserved
* Terminal state maintained

**Interruption-safe**: Maestro designed for this.

### Can I access my session from different devices?

Yes. **Multi-device support**:

* Same session on desktop, laptop, tablet, phone
* Synchronized state across all devices
* Answer asks from any device
* Real-time updates

**Use case**: Start on desktop, check progress on phone, resume on laptop.

## Performance and Scale

### How fast is Maestro?

**Varies by task**:

* Simple code generation: Seconds
* Complex feature implementation: Minutes to hours
* Research and analysis: Seconds to minutes
* Test execution: Depends on your tests

**Factors**:

* Model latency (inherent to LLMs)
* Sandbox execution time (real code takes real time)
* Validation thoroughness (quality over speed)

**Optimization**: Maestro prioritizes **correctness over speed**. Fast but wrong is useless.

### Can Maestro handle large codebases?

**Current capabilities**:

* Repositories up to \~10GB
* Thousands of files
* Complex architectures

**Context management**:

* View files selectively
* Use file search and analysis
* Pattern-based operations

**Best results**:

* Well-structured codebases
* Clear module boundaries
* Good documentation

**If very large**: Consider subsystem-focused sessions.

### What are Maestro's limits?

**Technical limits**:

* Repository size: \~10GB
* Session capacity: Token-based (manage via commands)
* Sandbox resources: 2 vCPU, 7 GB RAM default
* Public ports: Port 8080 only
* GPU: Not yet available

**Practical limits**:

* Works best on validatable projects
* Requires testable implementations
* Benefits from clear requirements
* Best with existing test infrastructure

**Not limits**:

* Number of sessions
* Session duration
* Complexity of problems
* Number of tools used

## Working with Maestro

### When should I use Maestro vs writing code myself?

**Use Maestro when**:

* Implementing complete features (not tiny changes)
* Need systematic validation (comprehensive testing)
* Working across many files
* Tackling unfamiliar domains
* Want evidence-driven development
* Speed matters (weeks → days compression)

**Use your IDE when**:

* Trivial changes (button color, typo fix)
* You already know exact implementation
* Rapid experimentation (trying something quickly)
* Preference for hands-on coding

**Hybrid approach**: Many users use both--Maestro for heavy lifting, IDE for final polish.

### How much should I guide vs let Maestro decide?

**Depends on**:

* Your experience with Maestro
* Complexity of problem
* Familiarity with domain
* Risk tolerance

**General guideline**:

* **Set goals clearly** (what success looks like)
* **Define constraints** (what must/must not happen)
* **Let Maestro propose approaches** (leverage its knowledge)
* **Validate thoroughly** (evidence required)

**Over time**: You'll develop intuition for when to intervene vs delegate.

### What if Maestro goes off track?

**Immediate correction**:

```
"Stop. This is going in the wrong direction. [Explain correct path]. Reset and start from [point]."
```

**Maestro will**:

* Acknowledge the correction
* Adjust approach
* Continue with new understanding

**Prevention**:

* Correct misunderstandings early
* Provide clear constraints upfront
* Validate at milestones, not just end

### Can Maestro work without internet?

**No**. Maestro requires internet for:

* Model API calls (core functionality)
* Sandbox connectivity
* Web research tools
* External service integration

**Offline work**: Not supported currently.

## Data and Privacy

### Where is my code stored?

**During session**:

* In your session state (cloud-hosted)
* In sandbox (temporary, isolated)
* Checkpoints (if persistence enabled)

**After session**:

* Checkpoints preserved per retention policy
* Or immediately deleted (your choice)
* Downloaded files on your machine

**Security**:

* Encrypted in transit and at rest
* Access controlled
* Isolated per user

### Can I delete my data?

Yes. **Data deletion**:

* Delete individual sessions
* Clear all session data
* Remove checkpoints
* Request complete account data deletion

**Immediate effect**: Data removed from active systems.

**Backups**: May persist in backups for limited time per retention policy.

### Is my session visible to iGent AI staff?

**Normal operation**: No

* Automated systems only
* No human access to session content

**Support requests**: Only with your permission

* If you request support
* With explicit consent
* Limited to debugging specific issue

**Monitoring**: Aggregate metrics only (no content)

## Billing and Costs

### How are credits charged?

**Usage-based charges**:

* Model API calls (varies by model)
* Sandbox compute time
* Storage and bandwidth

**Factors affecting cost**:

* Session length (more turns = more cost)
* Model choice (some models more expensive)
* Sandbox usage (execution time)
* File storage size

**Optimization**:

* Manage capacity to reduce token usage
* Use appropriate models for tasks
* Minimize unnecessary sandbox operations

### What if I run out of credits mid-session?

**Low balance warning**: Notification before credits exhausted

**Options**:

1. `/topup` command for quick credit purchase
2. Auto-reload (if configured) purchases credits automatically
3. Pause session until credits added

**Session preservation**: Session state saved even if credits depleted

### Can I get refunds for unused credits?

**Policies vary**: Check current terms at [https://igent.ai/](https://igent.ai/)

**Typical policies**:

* Subscription fees: Subject to cancellation policy
* Unused credits: May or may not roll over (plan-dependent)
* Refunds: Per terms of service

**Recommendation**: Review billing policies before subscribing.

## Technical Questions

### What programming languages does Maestro support?

**Fully supported** (with syntax highlighting, tools, validation):

* Python
* JavaScript/TypeScript
* Go
* Rust
* Java/Kotlin
* C/C++
* Ruby
* PHP
* Shell scripting

**Also works with**:

* Virtually any text-based language
* Configuration formats (YAML, JSON, TOML, XML)
* Markdown, HTML, CSS
* SQL, query languages

**Limitation**: Language-specific IDE features (linting, autocomplete) are in sandbox, not UI.

### Does Maestro support frameworks like React, Django, FastAPI?

Yes. Maestro has deep knowledge of major frameworks:

* **Frontend**: React, Vue, Angular, Next.js, Svelte
* **Backend**: Django, FastAPI, Express, Gin, Actix
* **Full-stack**: Next.js, Nuxt, SvelteKit
* **Mobile**: React Native, Flutter (code generation)
* **Data**: Pandas, NumPy, PyTorch, TensorFlow

**Framework-specific knowledge**:

* Idioms and best practices
* Common patterns
* Testing approaches
* Performance optimization
* Security considerations

### Can Maestro help with mobile development?

**Yes**, for code generation and logic:

* React Native (JavaScript/TypeScript)
* Flutter (Dart)
* SwiftUI/UIKit (Swift)
* Jetpack Compose (Kotlin)

**Limitations**:

* No mobile device emulator in sandbox
* Cannot test iOS apps (requires macOS)
* Android testing possible but limited

**Best use cases**:

* Business logic implementation
* API client code
* State management
* Unit tests

**UI testing**: Use external emulators or devices.

### Does Maestro work with databases?

Yes. **Database operations**:

* Schema design
* Migration scripts
* Query optimization
* ORM integration (SQLAlchemy, Prisma, etc.)

**Testing**:

* Local PostgreSQL/MySQL in sandbox
* SQLite for testing
* Can connect to external databases with credentials

**Example**:

```
"Design database schema for multi-tenant SaaS.

Requirements:
- PostgreSQL with row-level security
- Tenant isolation
- Migration scripts with Alembic
- Comprehensive tests

Validate by running migrations on test database in sandbox."
```

## Comparison to Other Tools

### Maestro vs Cursor

**Cursor**:

* IDE extension
* Real-time autocomplete
* Fast inline suggestions
* Works with your editor

**Maestro**:

* Complete implementation partner
* Autonomous execution and validation
* Handles entire features
* Includes testing and benchmarking

**Use together**: Cursor for inline editing, Maestro for feature implementation.

### Maestro vs ChatGPT/Claude

**ChatGPT/Claude**:

* General-purpose chatbots
* Code generation via conversation
* No execution environment
* No validation
* You copy/paste code

**Maestro**:

* Specialized engineering system
* Orchestrates multiple models
* Executes and tests code
* Validates all claims
* Delivers tested, working code

**Difference**: Maestro proves code works, not just generates it.

### Maestro vs Replit/Glitch

**Replit/Glitch**:

* Browser-based IDEs
* Good for prototyping
* You write the code
* Instant deployment

**Maestro**:

* AI writes the code
* Comprehensive testing
* Production-ready output
* Validation-first approach

**Overlap**: Both provide execution environments. Difference is who writes the code and to what standard.

## Getting Help

### I'm stuck. What should I do?

**In order**:

1. **Ask Maestro**: "I'm stuck with \[X]. How should I proceed?"
2. **Check documentation**: Search for relevant topic
3. **Try different approach**: "Let's try a different way"
4. **Use commands**: `/reset-sandbox`, `/forget`, `/refresh`
5. **Start fresh**: New session with lesson learned
6. **Contact support**: [support@igent.ai](mailto:support@igent.ai)

**Usually**: Maestro can help you get unstuck by reformulating the problem.

### Something isn't working as documented

**First**: Verify you're following documentation correctly

**Then**: Report the issue:

* What documentation says
* What actually happened
* Steps to reproduce
* Session ID if relevant

**Where**: Support email or appropriate feedback channel

### I have a feature request

**We want to hear it**:

* Email: [support@igent.ai](mailto:support@igent.ai)
* Include use case and benefit
* Explain why current features don't solve it

**Priorities driven by**:

* User demand
* Strategic value
* Technical feasibility
* Resource availability

### Is there a community?

**Current channels**: Check [https://igent.ai/](https://igent.ai/) for:

* Community forums
* Discord server
* Office hours
* User groups

**Contribute**:

* Share workflows and patterns
* Provide feedback
* Request features
* Help other users

## Next Steps

Questions answered? Explore:

* **[Best Practices](reference/best-practices)**: Production-ready patterns
* **[Billing Guide](reference/billing)**: Detailed billing information
* **[Models](reference/models)**: How Maestro's AI models work