---
metadata:
  - name: generator
    content: Diplodoc Platform v5.71.0
alternate:
  - https://sourcecraft.dev/portal/docs/en/vibecraft/concepts/how-it-works.md
  - https://sourcecraft.dev/portal/docs/en/vibecraft/concepts/how-it-works.md
  - https://sourcecraft.dev/portal/docs/ru/vibecraft/concepts/how-it-works.md
  - href: https://sourcecraft.dev/portal/docs/en/vibecraft/concepts/how-it-works.md
    type: text/markdown
    title: Markdown version
  - href: https://sourcecraft.dev/portal/docs/en/llms.txt?revision=r22227429
    rel: describedby
title: How VibeCraft works
description: Learn how VibeCraft works with the SourceCraft repository and remote runtime.
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt?revision=r22227429


# How VibeCraft works

The [SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md) [repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos) is the main source of the project's relevant code and securely saved changes. VibeCraft works with a project using the [SourceCraft Spaces](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/spaces.md) remote runtime connected to the project. It holds the repository's working copy the agent uses. The same runtime is used to run the application and generate its preview version.

![image](../../_assets/sourcecraft/vibecraft-architecture.svg)

## Processing a task {#workflow}

1. Before starting a task, VibeCraft updates the working copy to the current state of the [target branch](https://sourcecraft.dev/portal/docs/en/sourcecraft/tutorials/quickstart-git.md#branches).
1. The agent changes files and runs checks and the application. It uses the [Docker Compose](https://docs.docker.com/compose/) configuration from the project to run the application.
1. After successfully completing the task, the agent creates a [commit](https://sourcecraft.dev/portal/docs/en/sourcecraft/tutorials/quickstart-git.md#commits) and sends the result to SourceCraft.

{% note warning %}

The result is only considered securely saved if it appears in the SourceCraft repository. Changes left only in the remote runtime may be lost when updating the working copy, as well as after an error, task stop, or when exceeding the execution timeout.

{% endnote %}

## Restrictions and possible issues {#troubleshooting}

### Task is complete within 30 minutes {#task-timeout}

If the agent failed to complete the task within 30 minutes, the result may not be pushed to SourceCraft.

{% note tip %}

Break a large task into several subtasks and, after completing each subtask, check its commit in the repository.

{% endnote %}

### Why the agent may overlook a new commit {#git-sync}

If you pushed the changes to the repository yourself, write about it in the VibeCraft chat. Specify the commit or changed files the agent should process. Changes only existing in the remote runtime's working copy are not available in the chat.

### Changing files in parallel may result in a conflict {#git-conflict}

{% note warning %}

Do not change the same files in the target branch while the agent is implementing the task. Otherwise, you may get a conflict when sending the result, and the agent's changes will not be pushed to SourceCraft. You cannot restore partial changes from the remote runtime.

{% endnote %}

If a conflict occurred, re-implement the task after making sure the target branch includes all the required changes.

### Stopping a task does not ensure a save or rollback {#stop-task}

To stop an active task, under the developer section, click ![image](../../_assets/console-icons/circle-stop.svg) **Stop**.

{% note warning %}

It will stop the task implementation, but will not ensure saving a partial result, creating a commit, or rolling the project back.

{% endnote %}

## How to safely work in VibeCraft and via Git at the same time {#recommendations}

1. Before starting a task, push all the required changes to SourceCraft.
1. Write about the commit you added in the VibeCraft chat.
1. Do not change the same files in the target branch while the agent is implementing the task.
1. After completion, make sure the final commit appears in SourceCraft.
1. Store all the important data in the repository or external storage rather than only in the remote runtime.

If your final commit is missing in SourceCraft, check if the execution timeout has expired and the target branch has been changed in parallel. Then push your current changes to the repository, write about them to the agent in the chat, and re-implement the task.

## Technical features {#tech}

VibeCraft uses the following SourceCraft and [Yandex Cloud](https://yandex.cloud/en) components:

* [Code Assistant](https://sourcecraft.dev/portal/docs/en/code-assistant/concepts/index.md) LLM ensemble used to engineer the application concept, write and test code.
* [SourceCraft Spaces remote runtime](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/spaces.md) with the repository's working copy for the agent.
* SourceCraft [repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos) used to store code.
* SourceCraft [CI/CD](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md) used to preview the application and automate deployment.
* [Registry in Yandex Container Registry](https://yandex.cloud/en/docs/container-registry/concepts/registry) for storing [Docker images](https://yandex.cloud/en/docs/container-registry/concepts/docker-image) that contain the application.
* [Container in Yandex Serverless Containers](https://yandex.cloud/en/docs/serverless-containers/concepts/container) for running the application.
* [Serverless database in Yandex Managed Service for YDB](https://yandex.cloud/en/docs/ydb/concepts/resources#serverless) for storing the application status.
* [Yandex Lockbox secret](https://yandex.cloud/en/docs/lockbox/concepts/secret) for storing sensitive data.

{% note info %}

When [associating your own domain](https://sourcecraft.dev/portal/docs/en/vibecraft/operations/attach-domain.md) a [Yandex API Gateway](https://yandex.cloud/en/docs/api-gateway/concepts/index) is also created. If the domain management is delegated to [Yandex Cloud DNS](https://yandex.cloud/en/docs/dns/concepts/), a [DNS zone](https://yandex.cloud/en/docs/dns/concepts/dns-zone) and [resource records](https://yandex.cloud/en/docs/dns/concepts/resource-record) are created as well.

{% endnote %}

You can manage Yandex Cloud resources from the SourceCraft repository via a secure [service connection](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/service-connections.md).

#### Useful links {#see-also}

* [Getting started with VibeCraft](https://sourcecraft.dev/portal/docs/en/vibecraft/index.md)
* [VibeCraft overview](https://sourcecraft.dev/portal/docs/en/vibecraft/concepts/index.md)
* [FAQ about VibeCraft](https://sourcecraft.dev/portal/docs/en/vibecraft/qa.md)
* [VibeCraft quotas and limits](https://sourcecraft.dev/portal/docs/en/vibecraft/concepts/limits.md)
