Import a folder or ZIP

Folder and ZIP import are production workflows for bringing one multi-file project into AgentGrid.io as one new artifact. Import is a copy, not a sync with your local source.

Availability and limits

Each import accepts one folder or one .zip, up to 50 MiB and 1,000 files. Choose the destination workspace before import and make sure you can create there.

Include source files and assets. Exclude dependencies such as node_modules, build output, secrets, and anything you would normally ignore. An app needs an entry point, the file that starts the app when it opens. This includes index.html. A markdown artifact needs one or more .md files.

Import in the app

1. Choose New → Upload Folder for a folder or New → Import from ZIP for an archive.
2. Select one folder or .zip and the destination workspace when prompted.
3. Confirm the intended result where the flow asks: app or markdown.
4. Wait for the new artifact to open, then verify its type, files, assets, and rendered result.

Agent and CLI route

A connected agent can import the same source. The public CLI's anima create import mode accepts a folder or .zip, --artifact-type app|markdown, and an optional workspace. The workspace may be omitted only when the agent can create in exactly one workspace; otherwise select one explicitly.

What happens next

Import creates a new artifact with its own URL and History. Later local edits do not update it. To continue work, edit that artifact; importing the source again creates another artifact.

Errors and recovery

• Over 50 MiB or 1,000 files: remove dependencies/build output or split the source intentionally.
• Invalid paths or malformed ZIP: rebuild the archive with ordinary relative paths and retry.
• Unsupported structure or missing entry point: add the file that starts the app, including index.html, or add .md content and choose the matching artifact type.
• Workspace denial: ask a workspace manager for create access or select another authorized workspace.
• Artifact quota: follow the upgrade path; do not retry unchanged.
• Blank app: verify index.html and its relative assets.

See Artifact types, Workspace access, and Limits and quotas.

Questions and answers

What can one import contain? One folder or one .zip, up to 50 MiB and 1,000 files.

What should I leave out? Exclude dependencies such as node_modules, build output, ignored files, and secrets.

How do I verify an import? Check the destination workspace, artifact type, files, assets, entry point, and rendered result.

Does re-importing update the artifact? No. It creates a second artifact; continue editing the existing artifact instead.

Direct answer

Folder and ZIP imports are live. One folder or one .zip creates one new app or markdown artifact; it does not establish synchronization with the local source.

Input contract

• Maximum transport size: 50 MiB.
• Maximum file count: 1,000.
• Include source and assets; exclude node_modules, build output, ignored files, and secrets.
• app requires an entry point: the file that starts the app when it opens, including index.html.
• markdown requires at least one .md file.

Human UI route

For a folder, instruct the human to use New → Upload Folder. For an archive, use New → Import from ZIP. The human selects one source, chooses the destination workspace when prompted, confirms app or markdown where requested, and verifies the new artifact.

Agent/CLI route

The public CLI's anima create import mode accepts a folder or .zip plus --artifact-type app|markdown. Supply the workspace when the agent can create in more than one workspace; there is no default in that case. Do not guess the destination.

After creation, verify the returned artifact by listing/opening it and checking workspace, type, file set, entry point, and rendered result. A lost response can leave a created artifact, so list recent artifacts before retrying.

Failure classification

Importing again creates a second artifact. Continue updates on the created artifact. See Artifact types, Workspace access, and Limits.

Questions and answers

Which identifiers and options are required? Use the discovered destination workspace ID when more than one workspace is writable, plus --artifact-type app|markdown for CLI import mode.

What must source validation confirm? One source within 50 MiB and 1,000 files, no secrets or dependencies, and either an app entry point or .md content.

What result must be verified? List or open the returned artifact and check workspace, type, files, entry point, and rendering.

What happens after a lost create response? List recent artifacts before retrying because another import would create a second artifact.