[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-71289":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},71289,"ai-town","a16z-infra\u002Fai-town","a16z-infra","A MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize.","https:\u002F\u002Fconvex.dev\u002Fai-town",null,"TypeScript",9986,1108,82,66,0,27,50,141,81,40.13,"MIT License",false,"main",true,[],"2026-06-12 02:02:50","# AI Town 🏠💻💌\n\n[Live Demo](https:\u002F\u002Fwww.convex.dev\u002Fai-town)\n\n[Join our community Discord: AI Stack Devs](https:\u002F\u002Fdiscord.gg\u002FPQUmTBTGmT)\n\n\u003Cimg width=\"1454\" alt=\"Screen Shot 2023-08-14 at 10 01 00 AM\" src=\"https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-town\u002Fassets\u002F3489963\u002Fa4c91f17-23ed-47ec-8c4e-9f9a8505057d\">\n\nAI Town is a virtual town where AI characters live, chat and socialize.\n\nThis project is a deployable starter kit for easily building and customizing your own version of AI\ntown. Inspired by the research paper\n[_Generative Agents: Interactive Simulacra of Human Behavior_](https:\u002F\u002Farxiv.org\u002Fpdf\u002F2304.03442.pdf).\n\nThe primary goal of this project, beyond just being a lot of fun to work on, is to provide a\nplatform with a strong foundation that is meant to be extended. The back-end natively supports\nshared global state, transactions, and a simulation engine and should be suitable from everything\nfrom a simple project to play around with to a scalable, multi-player game. A secondary goal is to\nmake a JS\u002FTS framework available as most simulators in this space (including the original paper\nabove) are written in Python.\n\n## Overview\n\n- 💻 [Stack](#stack)\n- 🧠 [Installation](#installation) (cloud, local, Docker, self-host, Fly.io, ...)\n- 💻️ [Windows Pre-requisites](#windows-installation)\n- 🤖 [Configure your LLM of choice](#connect-an-llm) (Ollama, OpenAI, Together.ai, ...)\n- 👤 [Customize - YOUR OWN simulated world](#customize-your-own-simulation)\n- 👩‍💻 [Deploying to production](#deploy-the-app-to-production)\n- 🐛 [Troubleshooting](#troubleshooting)\n\n## Stack\n\n- Game engine, database, and vector search: [Convex](https:\u002F\u002Fconvex.dev\u002F)\n- Auth (Optional): [Clerk](https:\u002F\u002Fclerk.com\u002F)\n- Default chat model is `llama3` and embeddings with `mxbai-embed-large`.\n- Local inference: [Ollama](https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama)\n- Configurable for other cloud LLMs: [Together.ai](https:\u002F\u002Ftogether.ai\u002F) or anything that speaks the\n  [OpenAI API](https:\u002F\u002Fplatform.openai.com\u002F). PRs welcome to add more cloud provider support.\n- Background Music Generation: [Replicate](https:\u002F\u002Freplicate.com\u002F) using\n  [MusicGen](https:\u002F\u002Fhuggingface.co\u002Fspaces\u002Ffacebook\u002FMusicGen)\n\nOther credits:\n\n- Pixel Art Generation: [Replicate](https:\u002F\u002Freplicate.com\u002F),\n  [Fal.ai](https:\u002F\u002Fserverless.fal.ai\u002Flora)\n- All interactions, background music and rendering on the \u003CGame\u002F> component in the project are\n  powered by [PixiJS](https:\u002F\u002Fpixijs.com\u002F).\n- Tilesheet:\n  - https:\u002F\u002Fopengameart.org\u002Fcontent\u002F16x16-game-assets by George Bailey\n  - https:\u002F\u002Fopengameart.org\u002Fcontent\u002F16x16-rpg-tileset by hilau\n- We used https:\u002F\u002Fgithub.com\u002Fpierpo\u002Fphaser3-simple-rpg for the original POC of this project. We have\n  since re-wrote the whole app, but appreciated the easy starting point\n- Original assets by [ansimuz](https:\u002F\u002Fopengameart.org\u002Fcontent\u002Ftiny-rpg-forest)\n- The UI is based on original assets by\n  [Mounir Tohami](https:\u002F\u002Fmounirtohami.itch.io\u002Fpixel-art-gui-elements)\n\n# Installation\n\nThe overall steps are:\n\n1. [Build and deploy](#build-and-deploy)\n2. [Connect it to an LLM](#connect-an-llm)\n\n## Build and Deploy\n\nThere are a few ways to run the app on top of Convex (the backend).\n\n1. The standard Convex setup, where you develop locally or in the cloud. This requires a Convex\n   account(free). This is the easiest way to depoy it to the cloud and seriously develop.\n2. If you want to try it out without an account and you're okay with Docker, the Docker Compose\n   setup is nice and self-contained.\n3. There's a community fork of this project offering a one-click install on\n   [Pinokio](https:\u002F\u002Fpinokio.computer\u002Fitem?uri=https:\u002F\u002Fgithub.com\u002Fcocktailpeanutlabs\u002Faitown) for\n   anyone interested in running but not modifying it 😎.\n4. You can also deploy it to [Fly.io](https:\u002F\u002Ffly.io\u002F). See [.\u002Ffly](.\u002Ffly) for instructions.\n\n### Standard Setup\n\nNote, if you're on Windows, see [below](#windows-installation).\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-town.git\ncd ai-town\nnpm install\n```\n\nThis will require logging into your Convex account, if you haven't already.\n\nTo run it:\n\n```sh\nnpm run dev\n```\n\nYou can now visit http:\u002F\u002Flocalhost:5173.\n\nIf you'd rather run the frontend and backend separately (which syncs your backend functions as\nthey're saved), you can run these in two terminals:\n\n```bash\nnpm run dev:frontend\nnpm run dev:backend\n```\n\nSee [package.json](.\u002Fpackage.json) for details.\n\n### Using Docker Compose with self-hosted Convex\n\nYou can also run the Convex backend with the self-hosted Docker container. Here we'll set it up to\nrun the frontend, backend, and dashboard all via docker compose.\n\n```sh\ndocker compose up --build -d\n```\n\nThe container will keep running in the background if you pass `-d`. After you've done it once, you\ncan `stop` and `start` services.\n\n- The frontend will be running on http:\u002F\u002Flocalhost:5173.\n- The backend will be running on http:\u002F\u002Flocalhost:3210 (3211 for the http api).\n- The dashboard will be running on http:\u002F\u002Flocalhost:6791.\n\nTo log into the dashboard and deploy from the convex CLI, you will need to generate an admin key.\n\n```sh\ndocker compose exec backend .\u002Fgenerate_admin_key.sh\n```\n\nAdd it to your `.env.local` file. Note: If you run `down` and `up`, you'll have to generate the key\nagain and update the `.env.local` file.\n\n```sh\n# in .env.local\nCONVEX_SELF_HOSTED_ADMIN_KEY=\"\u003Cadmin-key>\" # Ensure there are quotes around it\nCONVEX_SELF_HOSTED_URL=\"http:\u002F\u002F127.0.0.1:3210\"\n```\n\nThen set up the Convex backend (one time):\n\n```sh\nnpm run predev\n```\n\nTo continuously deploy new code to the backend and print logs:\n\n```sh\nnpm run dev:backend\n```\n\nTo see the dashboard, visit `http:\u002F\u002Flocalhost:6791` and provide the admin key you generated earlier.\n\n### Configuring Docker for Ollama\n\nIf you'll be using Ollama for local inference, you'll need to configure Docker to connect to it.\n\n```sh\nnpx convex env set OLLAMA_HOST http:\u002F\u002Fhost.docker.internal:11434\n```\n\nTo test the connection (after you [have it running](#ollama-default)):\n\n```sh\ndocker compose exec backend \u002Fbin\u002Fbash curl http:\u002F\u002Fhost.docker.internal:11434\n```\n\nIf it says \"Ollama is running\", it's good! Otherwise, check out the\n[Troubleshooting](#troubleshooting) section.\n\n## Connect an LLM\n\nNote: If you want to run the backend in the cloud, you can either use a cloud-based LLM API, like\nOpenAI or Together.ai or you can proxy the traffic from the cloud to your local Ollama. See\n[below](#using-local-inference-from-a-cloud-deployment) for instructions.\n\n### Ollama (default)\n\nBy default, the app tries to use Ollama to run it entirely locally.\n\n1. Download and install [Ollama](https:\u002F\u002Follama.com\u002F).\n2. Open the app or run `ollama serve` in a terminal. `ollama serve` will warn you if the app is\n   already running.\n3. Run `ollama pull llama3` to have it download `llama3`.\n4. Test it out with `ollama run llama3`.\n\nOllama model options can be found [here](https:\u002F\u002Follama.ai\u002Flibrary).\n\nIf you want to customize which model to use, adjust convex\u002Futil\u002Fllm.ts or set\n`npx convex env set OLLAMA_MODEL # model`. If you want to edit the embedding model:\n\n1. Change the `OLLAMA_EMBEDDING_DIMENSION` in `convex\u002Futil\u002Fllm.ts` and ensure:\n   `export const EMBEDDING_DIMENSION = OLLAMA_EMBEDDING_DIMENSION;`\n2. Set `npx convex env set OLLAMA_EMBEDDING_MODEL # model`.\n\nNote: You might want to set `NUM_MEMORIES_TO_SEARCH` to `1` in constants.ts, to reduce the size of\nconversation prompts, if you see slowness.\n\n### OpenAI\n\nTo use OpenAI, you need to:\n\n```ts\n\u002F\u002F In convex\u002Futil\u002Fllm.ts change the following line:\nexport const EMBEDDING_DIMENSION = OPENAI_EMBEDDING_DIMENSION;\n```\n\nSet the `OPENAI_API_KEY` environment variable. Visit https:\u002F\u002Fplatform.openai.com\u002Faccount\u002Fapi-keys if\nyou don't have one.\n\n```sh\nnpx convex env set OPENAI_API_KEY 'your-key'\n```\n\nOptional: choose models with `OPENAI_CHAT_MODEL` and `OPENAI_EMBEDDING_MODEL`.\n\n### Together.ai\n\nTo use Together.ai, you need to:\n\n```ts\n\u002F\u002F In convex\u002Futil\u002Fllm.ts change the following line:\nexport const EMBEDDING_DIMENSION = TOGETHER_EMBEDDING_DIMENSION;\n```\n\nSet the `TOGETHER_API_KEY` environment variable. Visit https:\u002F\u002Fapi.together.xyz\u002Fsettings\u002Fapi-keys if\nyou don't have one.\n\n```sh\nnpx convex env set TOGETHER_API_KEY 'your-key'\n```\n\nOptional: choose models via `TOGETHER_CHAT_MODEL`, `TOGETHER_EMBEDDING_MODEL`. The embedding model's\ndimension must match `EMBEDDING_DIMENSION`.\n\n### Other OpenAI-compatible API\n\nYou can use any OpenAI-compatible API, such as Anthropic, Groq, or Azure.\n\n- Change the `EMBEDDING_DIMENSION` in `convex\u002Futil\u002Fllm.ts` to match the dimension of your embedding\n  model.\n- Edit `getLLMConfig` in `llm.ts` or set environment variables:\n\n```sh\nnpx convex env set LLM_API_URL 'your-url'\nnpx convex env set LLM_API_KEY 'your-key'\nnpx convex env set LLM_MODEL 'your-chat-model'\nnpx convex env set LLM_EMBEDDING_MODEL 'your-embedding-model'\n```\n\nNote: if `LLM_API_KEY` is not required, don't set it.\n\n### Note on changing the LLM provider or embedding model:\n\nIf you change the LLM provider or embedding model, you should delete your data and start over. The\nembeddings used for memory are based on the embedding model you choose, and the dimension of the\nvector database must match the embedding model's dimension. See\n[below](#wiping-the-database-and-starting-over) for how to do that.\n\n## Customize your own simulation\n\nNOTE: every time you change character data, you should re-run `npx convex run testing:wipeAllTables`\nand then `npm run dev` to re-upload everything to Convex. This is because character data is sent to\nConvex on the initial load. However, beware that `npx convex run testing:wipeAllTables` WILL wipe\nall of your data.\n\n1. Create your own characters and stories: All characters and stories, as well as their spritesheet\n   references are stored in [characters.ts](.\u002Fdata\u002Fcharacters.ts). You can start by changing\n   character descriptions.\n\n2. Updating spritesheets: in `data\u002Fcharacters.ts`, you will see this code:\n\n   ```ts\n   export const characters = [\n     {\n       name: 'f1',\n       textureUrl: '\u002Fassets\u002F32x32folk.png',\n       spritesheetData: f1SpritesheetData,\n       speed: 0.1,\n     },\n     ...\n   ];\n   ```\n\n   You should find a sprite sheet for your character, and define sprite motion \u002F assets in the\n   corresponding file (in the above example, `f1SpritesheetData` was defined in f1.ts)\n\n3. Update the Background (Environment): The map gets loaded in `convex\u002Finit.ts` from\n   `data\u002Fgentle.js`. To update the map, follow these steps:\n\n   - Use [Tiled](https:\u002F\u002Fwww.mapeditor.org\u002F) to export tilemaps as a JSON file (2 layers named\n     bgtiles and objmap)\n   - Use the `convertMap.js` script to convert the JSON to a format that the engine can use.\n\n   ```console\n   node data\u002FconvertMap.js \u003CmapDataPath> \u003CassetPath> \u003Ctilesetpxw> \u003Ctilesetpxh>\n   ```\n\n   - `\u003CmapDataPath>`: Path to the Tiled JSON file.\n   - `\u003CassetPath>`: Path to tileset images.\n   - `\u003Ctilesetpxw>`: Tileset width in pixels.\n   - `\u003Ctilesetpxh>`: Tileset height in pixels. Generates `converted-map.js` that you can use like\n     `gentle.js`\n\n4. Adding background music with Replicate (Optional)\n\n   For Daily background music generation, create a [Replicate](https:\u002F\u002Freplicate.com\u002F) account and\n   create a token in your Profile's [API Token page](https:\u002F\u002Freplicate.com\u002Faccount\u002Fapi-tokens).\n   `npx convex env set REPLICATE_API_TOKEN # token`\n\n   This only works if you can receive the webhook from Replicate. If it's running in the normal\n   Convex cloud, it will work by default. If you're self-hosting, you'll need to configure it to hit\n   your app's url on `\u002Fhttp`. If you're using Docker Compose, it will be `http:\u002F\u002Flocalhost:3211`,\n   but you'll need to proxy the traffic to your local machine.\n\n   **Note**: The simulation will pause after 5 minutes if the window is idle. Loading the page will\n   unpause it. You can also manually freeze & unfreeze the world with a button in the UI. If you\n   want to run the world without the browser, you can comment-out the \"stop inactive worlds\" cron in\n   `convex\u002Fcrons.ts`.\n\n   - Change the background music by modifying the prompt in `convex\u002Fmusic.ts`\n   - Change how often to generate new music at `convex\u002Fcrons.ts` by modifying the\n     `generate new background music` job\n\n## Commands to run \u002F test \u002F debug\n\n**To stop the back end, in case of too much activity**\n\nThis will stop running the engine and agents. You can still run queries and run functions to debug.\n\n```bash\nnpx convex run testing:stop\n```\n\n**To restart the back end after stopping it**\n\n```bash\nnpx convex run testing:resume\n```\n\n**To kick the engine in case the game engine or agents aren't running**\n\n```bash\nnpx convex run testing:kick\n```\n\n**To archive the world**\n\nIf you'd like to reset the world and start from scratch, you can archive the current world:\n\n```bash\nnpx convex run testing:archive\n```\n\nThen, you can still look at the world's data in the dashboard, but the engine and agents will no\nlonger run.\n\nYou can then create a fresh world with `init`.\n\n```bash\nnpx convex run init\n```\n\n**To pause your backend deployment**\n\nYou can go to the [dashboard](https:\u002F\u002Fdashboard.convex.dev) to your deployment settings to pause and\nun-pause your deployment. This will stop all functions, whether invoked from the client, scheduled,\nor as a cron job. See this as a last resort, as there are gentler ways of stopping above.\n\n## Windows Installation\n\n### Prerequisites\n\n1. **Windows 10\u002F11 with WSL2 installed**\n2. **Internet connection**\n\nSteps:\n\n1. Install WSL2\n\n   First, you need to install WSL2. Follow\n   [this guide](https:\u002F\u002Fdocs.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall) to set up WSL2 on your Windows\n   machine. We recommend using Ubuntu as your Linux distribution.\n\n2. Update Packages\n\n   Open your WSL terminal (Ubuntu) and update your packages:\n\n   ```sh\n   sudo apt update\n   ```\n\n3. Install NVM and Node.js\n\n   NVM (Node Version Manager) helps manage multiple versions of Node.js. Install NVM and Node.js 18\n   (the stable version):\n\n   ```sh\n   curl -o- https:\u002F\u002Fraw.githubusercontent.com\u002Fnvm-sh\u002Fnvm\u002Fv0.39.2\u002Finstall.sh | bash\n   export NVM_DIR=\"$([ -z \"${XDG_CONFIG_HOME-}\" ] && printf %s \"${HOME}\u002F.nvm\" || printf %s \"${XDG_CONFIG_HOME}\u002Fnvm\")\"\n   [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && \\. \"$NVM_DIR\u002Fnvm.sh\"\n   source ~\u002F.bashrc\n   nvm install 18\n   nvm use 18\n   ```\n\n4. Install Python and Pip\n\n   Python is required for some dependencies. Install Python and Pip:\n\n   ```sh\n   sudo apt-get install python3 python3-pip sudo ln -s \u002Fusr\u002Fbin\u002Fpython3 \u002Fusr\u002Fbin\u002Fpython\n   ```\n\nAt this point, you can follow the instructions [above](#installation).\n\n## Deploy the app to production\n\n### Deploy Convex functions to prod environment\n\nBefore you can run the app, you will need to make sure the Convex functions are deployed to its\nproduction environment. Note: this is assuming you're using the default Convex cloud product.\n\n1. Run `npx convex deploy` to deploy the convex functions to production\n2. Run `npx convex run init --prod`\n\nTo transfer your local data to the cloud, you can run `npx convex export` and then import it with\n`npx convex import --prod`.\n\nIf you have existing data you want to clear, you can run\n`npx convex run testing:wipeAllTables --prod`\n\n### Adding Auth (Optional)\n\nYou can add clerk auth back in with `git revert b44a436`. Or just look at that diff for what changed\nto remove it.\n\n**Make a Clerk account**\n\n- Go to https:\u002F\u002Fdashboard.clerk.com\u002F and click on \"Add Application\"\n- Name your application and select the sign-in providers you would like to offer users\n- Create Application\n- Add `VITE_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` to `.env.local`\n\n```bash\nVITE_CLERK_PUBLISHABLE_KEY=pk_***\nCLERK_SECRET_KEY=sk_***\n```\n\n- Go to JWT Templates and create a new Convex Template.\n- Copy the JWKS endpoint URL for use below.\n\n```sh\nnpx convex env set CLERK_ISSUER_URL # e.g. https:\u002F\u002Fyour-issuer-url.clerk.accounts.dev\u002F\n```\n\n### Deploy the frontend to Vercel\n\n- Register an account on Vercel and then [install the Vercel CLI](https:\u002F\u002Fvercel.com\u002Fdocs\u002Fcli).\n- **If you are using Github Codespaces**: You will need to\n  [install the Vercel CLI](https:\u002F\u002Fvercel.com\u002Fdocs\u002Fcli) and authenticate from your codespaces cli by\n  running `vercel login`.\n- Deploy the app to Vercel with `vercel --prod`.\n\n## Using local inference from a cloud deployment\n\nWe support using [Ollama](https:\u002F\u002Fgithub.com\u002Fjmorganca\u002Follama) for conversation generations. To have\nit accessible from the web, you can use Tunnelmole or Ngrok or similar so the cloud backend can send\nrequests to Ollama running on your local machine.\n\nSteps:\n\n1. Set up either Tunnelmole or Ngrok.\n2. Add Ollama endpoint to Convex\n   ```sh\n   npx convex env set OLLAMA_HOST # your tunnelmole\u002Fngrok unique url from the previous step\n   ```\n3. Update Ollama domains Ollama has a list of accepted domains. Add the ngrok domain so it won't\n   reject traffic. see [ollama.ai](https:\u002F\u002Follama.ai) for more details.\n\n### Using Tunnelmole\n\n[Tunnelmole](https:\u002F\u002Fgithub.com\u002Frobbie-cahill\u002Ftunnelmole-client) is an open source tunneling tool.\n\nYou can install Tunnelmole using one of the following options:\n\n- NPM: `npm install -g tunnelmole`\n- Linux: `curl -s https:\u002F\u002Ftunnelmole.com\u002Fsh\u002Finstall-linux.sh | sudo bash`\n- Mac:\n  `curl -s https:\u002F\u002Ftunnelmole.com\u002Fsh\u002Finstall-mac.sh --output install-mac.sh && sudo bash install-mac.sh`\n- Windows: Install with NPM, or if you don't have NodeJS installed, download the `exe` file for\n  Windows [here](https:\u002F\u002Ftunnelmole.com\u002Fdownloads\u002Ftmole.exe) and put it somewhere in your PATH.\n\nOnce Tunnelmole is installed, run the following command:\n\n```\ntmole 11434\n```\n\nTunnelmole should output a unique url once you run this command.\n\n### Using Ngrok\n\nNgrok is a popular closed source tunneling tool.\n\n- [Install Ngrok](https:\u002F\u002Fngrok.com\u002Fdocs\u002Fgetting-started\u002F)\n\nOnce ngrok is installed and authenticated, run the following command:\n\n```\nngrok http http:\u002F\u002Flocalhost:11434\n```\n\nNgrok should output a unique url once you run this command.\n\n## Troubleshooting\n\n### Wiping the database and starting over\n\nYou can wipe the database by running:\n\n```sh\nnpx convex run testing:wipeAllTables\n```\n\nThen reset with:\n\n```sh\nnpx convex run init\n```\n\n### Incompatible Node.js versions\n\nIf you encounter a node version error on the convex server upon application startup, please use node\nversion 18, which is the most stable. One way to do this is by\n[installing nvm](https:\u002F\u002Fnodejs.org\u002Fen\u002Fdownload\u002Fpackage-manager) and running `nvm install 18` and\n`nvm use 18`.\n\n### Reaching Ollama\n\nIf you're having trouble with the backend communicating with Ollama, it depends on your setup how to\ndebug:\n\n1. If you're running directly on Windows, see\n   [Windows Ollama connection issues](#windows-ollama-connection-issues).\n2. If you're using **Docker**, see\n   [Docker to Ollama connection issues](#docker-to-ollama-connection-issues).\n3. If you're running locally, you can try the following:\n\n```sh\nnpx convex env set OLLAMA_HOST http:\u002F\u002Flocalhost:11434\n```\n\nBy default, the host is set to `http:\u002F\u002F127.0.0.1:11434`. Some systems prefer `localhost`\n¯\\_(ツ)\\_\u002F¯.\n\n### Windows Ollama connection issues\n\nIf the above didn't work after following the [windows](#windows-installation) and regular\n[installation](#installation) instructions, you can try the following, assuming you're **not** using\nDocker.\n\nIf you're using Docker, see the [next section](#docker-to-ollama-connection-issues) for Docker\ntroubleshooting.\n\nFor running directly on Windows, you can try the following:\n\n1. Install `unzip` and `socat`:\n\n   ```sh\n   sudo apt install unzip socat\n   ```\n\n2. Configure `socat` to Bridge Ports for Ollama\n\n   Run the following command to bridge ports:\n\n   ```sh\n   socat TCP-LISTEN:11434,fork TCP:$(cat \u002Fetc\u002Fresolv.conf | grep nameserver | awk '{print $2}'):11434 &\n   ```\n\n3. Test if it's working:\n\n   ```sh\n   curl http:\u002F\u002F127.0.0.1:11434\n   ```\n\n   If it responds OK, the Ollama API should be accessible.\n\n### Docker to Ollama connection issues\n\nIf you're having trouble with the backend communicating with Ollama, there's a couple things to\ncheck:\n\n1. Is Docker at least verion 18.03 ? That allows you to use the `host.docker.internal` hostname to\n   connect to the host from inside the container.\n\n2. Is Ollama running? You can check this by running `curl http:\u002F\u002Flocalhost:11434` from outside the\n   container.\n\n3. Is Ollama accessible from inside the container? You can check this by running\n   `docker compose exec backend curl http:\u002F\u002Fhost.docker.internal:11434`.\n\nIf 1 & 2 work, but 3 does not, you can use `socat` to bridge the traffic from inside the container\nto Ollama running on the host.\n\n1. Configure `socat` with the host's IP address (not the Docker IP).\n\n   ```sh\n   docker compose exec backend \u002Fbin\u002Fbash\n   HOST_IP=YOUR-HOST-IP\n   socat TCP-LISTEN:11434,fork TCP:$HOST_IP:11434\n   ```\n\n   Keep this running.\n\n2. Then from outside of the container:\n\n   ```sh\n   npx convex env set OLLAMA_HOST http:\u002F\u002Flocalhost:11434\n   ```\n\n3. Test if it's working:\n\n   ```sh\n   docker compose exec backend curl http:\u002F\u002Flocalhost:11434\n   ```\n\n   If it responds OK, the Ollama API is accessible. Otherwise, try changing the previous two to\n   `http:\u002F\u002F127.0.0.1:11434`.\n\n### Launching an Interactive Docker Terminal\n\nIf you wan to investigate inside the container, you can launch an interactive Docker terminal, for\nthe `frontend`, `backend` or `dashboard` service:\n\n```bash\ndocker compose exec frontend \u002Fbin\u002Fbash\n```\n\nTo exit the container, run `exit`.\n\n### Updating the browser list\n\n```bash\ndocker compose exec frontend npx update-browserslist-db@latest\n```\n\n# 🧑‍🏫 What is Convex?\n\n[Convex](https:\u002F\u002Fconvex.dev) is a hosted backend platform with a built-in database that lets you\nwrite your [database schema](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fschemas) and\n[server functions](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions) in\n[TypeScript](https:\u002F\u002Fdocs.convex.dev\u002Ftypescript). Server-side database\n[queries](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fquery-functions) automatically\n[cache](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fquery-functions#caching--reactivity) and\n[subscribe](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Freact#reactivity) to data, powering a\n[realtime `useQuery` hook](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Freact#fetching-data) in our\n[React client](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Freact). There are also clients for\n[Python](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Fpython), [Rust](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Frust),\n[ReactNative](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Freact-native), and\n[Node](https:\u002F\u002Fdocs.convex.dev\u002Fclient\u002Fjavascript), as well as a straightforward\n[HTTP API](https:\u002F\u002Fdocs.convex.dev\u002Fhttp-api\u002F).\n\nThe database supports [NoSQL-style documents](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fdocument-storage)\nwith [opt-in schema validation](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fschemas),\n[relationships](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fdocument-ids) and\n[custom indexes](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Findexes\u002F) (including on fields in nested objects).\n\nThe [`query`](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fquery-functions) and\n[`mutation`](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fmutation-functions) server functions have\ntransactional, low latency access to the database and leverage our\n[`v8` runtime](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fruntimes) with\n[determinism guardrails](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fruntimes#using-randomness-and-time-in-queries-and-mutations)\nto provide the strongest ACID guarantees on the market: immediate consistency, serializable\nisolation, and automatic conflict resolution via\n[optimistic multi-version concurrency control](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fadvanced\u002Focc) (OCC \u002F\nMVCC).\n\nThe [`action` server functions](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Factions) have access to external\nAPIs and enable other side-effects and non-determinism in either our\n[optimized `v8` runtime](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fruntimes) or a more\n[flexible `node` runtime](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fruntimes#nodejs-runtime).\n\nFunctions can run in the background via\n[scheduling](https:\u002F\u002Fdocs.convex.dev\u002Fscheduling\u002Fscheduled-functions) and\n[cron jobs](https:\u002F\u002Fdocs.convex.dev\u002Fscheduling\u002Fcron-jobs).\n\nDevelopment is cloud-first, with\n[hot reloads for server function](https:\u002F\u002Fdocs.convex.dev\u002Fcli#run-the-convex-dev-server) editing via\nthe [CLI](https:\u002F\u002Fdocs.convex.dev\u002Fcli),\n[preview deployments](https:\u002F\u002Fdocs.convex.dev\u002Fproduction\u002Fhosting\u002Fpreview-deployments),\n[logging and exception reporting integrations](https:\u002F\u002Fdocs.convex.dev\u002Fproduction\u002Fintegrations\u002F),\nThere is a [dashboard UI](https:\u002F\u002Fdocs.convex.dev\u002Fdashboard) to\n[browse and edit data](https:\u002F\u002Fdocs.convex.dev\u002Fdashboard\u002Fdeployments\u002Fdata),\n[edit environment variables](https:\u002F\u002Fdocs.convex.dev\u002Fproduction\u002Fenvironment-variables),\n[view logs](https:\u002F\u002Fdocs.convex.dev\u002Fdashboard\u002Fdeployments\u002Flogs),\n[run server functions](https:\u002F\u002Fdocs.convex.dev\u002Fdashboard\u002Fdeployments\u002Ffunctions), and more.\n\nThere are built-in features for [reactive pagination](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fpagination),\n[file storage](https:\u002F\u002Fdocs.convex.dev\u002Ffile-storage),\n[reactive text search](https:\u002F\u002Fdocs.convex.dev\u002Ftext-search),\n[vector search](https:\u002F\u002Fdocs.convex.dev\u002Fvector-search),\n[https endpoints](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fhttp-actions) (for webhooks),\n[snapshot import\u002Fexport](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fimport-export\u002F),\n[streaming import\u002Fexport](https:\u002F\u002Fdocs.convex.dev\u002Fproduction\u002Fintegrations\u002Fstreaming-import-export),\nand [runtime validation](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fschemas#validators) for\n[function arguments](https:\u002F\u002Fdocs.convex.dev\u002Ffunctions\u002Fargs-validation) and\n[database data](https:\u002F\u002Fdocs.convex.dev\u002Fdatabase\u002Fschemas#schema-validation).\n\nEverything scales automatically, and it’s [free to start](https:\u002F\u002Fwww.convex.dev\u002Fplans).\n","AI Town 是一个虚拟小镇，其中的AI角色可以生活、聊天和社交。该项目基于TypeScript开发，提供了一个可部署的启动工具包，方便用户构建和自定义自己的AI小镇版本。它支持共享全局状态、事务处理以及模拟引擎，适合从简单的实验项目到可扩展的多人游戏等多种场景。技术栈包括Convex作为游戏引擎和数据库，Ollama进行本地推理，并且支持多种云LLM服务如OpenAI等。此外，通过使用PixiJS渲染所有交互和背景音乐，确保了良好的用户体验。",2,"2026-06-11 03:36:59","high_star"]